relay-companion 0.1.474 → 0.1.476

package/bootstrap/relay-background-install.cjs

@@ -8,11 +8,11 @@ const { spawn } = require("node:child_process");
 const STATUS_VERSION = 1;
 
 function statusPath({ homeDir = os.homedir(), env = process.env } = {}) {
-  return env.RELAY_BACKGROUND_INSTALL_STATUS || path.join(homeDir, ".relay", "companion-install.json");
+  return env.RELAY_BACKGROUND_INSTALL_STATUS || path.join(env.RELAY_CONFIG_DIR || path.join(homeDir, ".relay"), "companion-install.json");
 }
 
 function logPath({ homeDir = os.homedir(), env = process.env } = {}) {
-  return env.RELAY_BACKGROUND_INSTALL_LOG || path.join(homeDir, ".relay", "companion-install.log");
+  return env.RELAY_BACKGROUND_INSTALL_LOG || path.join(env.RELAY_CONFIG_DIR || path.join(homeDir, ".relay"), "companion-install.log");
 }
 
 function atomicWriteJson(file, value) {

package/bootstrap/relay-skill.cjs

@@ -79,12 +79,33 @@ function defaultTargets({ homeDir = os.homedir(), env = process.env, host = "all
   if (selected === "all" || selected === "codex") {
     const root = env.CODEX_HOME || path.join(homeDir, ".codex");
     targets.push({ host: "codex", directory: path.join(root, "skills", SKILL_NAME) });
+    targets.push({ host: "codex", directory: path.join(homeDir, ".agents", "skills", SKILL_NAME) });
   }
   if (selected === "all" || selected === "claude") {
     const root = env.CLAUDE_HOME || path.join(homeDir, ".claude");
     targets.push({ host: "claude", directory: path.join(root, "skills", SKILL_NAME) });
   }
-  return targets;
+  return targets.filter((target, index) => targets.findIndex((other) => path.resolve(other.directory) === path.resolve(target.directory)) === index);
+}
+
+function configuredManifestUrl({ homeDir = os.homedir(), env = process.env, webOrigin } = {}) {
+  const configRoot = env.RELAY_CONFIG_DIR || path.join(homeDir, ".relay");
+  function read(file) {
+    try { return JSON.parse(fs.readFileSync(file, "utf8")); }
+    catch (error) { if (error.code === "ENOENT") return {}; throw error; }
+  }
+  const config = read(env.RELAY_CONFIG || path.join(configRoot, "config.json"));
+  const agent = config.webUrl || config.apiUrl ? {} : read(env.RELAY_AGENT_CONFIG || path.join(configRoot, "agent-protocol.json"));
+  const api = config.apiUrl || agent.apiUrl;
+  const knownOrigin = !api || api === "https://api.sendrelays.com" ? "https://sendrelays.com"
+    : api === "https://dev-api.sendrelays.com" ? "https://dev.sendrelays.com" : null;
+  const origin = webOrigin || env.RELAY_WEB_URL || config.webUrl || knownOrigin;
+  if (!origin) throw new Error("Relay requires a configured web origin for this API environment's skill updates.");
+  const url = new URL(origin);
+  if (url.protocol !== "https:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new Error("Relay requires a secure configured web origin for skill updates.");
+  }
+  return new URL("/skills/relay/manifest.json", url).href;
 }
 
 function pathInside(parent, child) {
@@ -223,12 +244,13 @@ async function installBundled(options = {}) {
 }
 
 async function updateFromRemote(options = {}) {
-  const manifestUrl = String(options.manifestUrl || MANIFEST_URL);
+  const manifestUrl = String(options.manifestUrl || configuredManifestUrl(options));
   const parsedUrl = new URL(manifestUrl);
   if (parsedUrl.protocol !== "https:" || parsedUrl.username || parsedUrl.password || parsedUrl.hash) {
     throw new Error("Relay requires a secure skill manifest URL.");
   }
   const manifest = parseManifest(await fetchBytes(parsedUrl.href, options), { requireRemote: true });
+  if (new URL(manifest.baseUrl).origin !== parsedUrl.origin) throw new Error("Relay's skill bundle must use the configured web origin.");
   return installManifest(manifest, (entry) => fetchBytes(`${manifest.baseUrl}/${entry.path.split("/").map(encodeURIComponent).join("/")}`, options), options);
 }
 
@@ -297,6 +319,7 @@ module.exports = {
   SKILL_NAME,
   STATE_FILE,
   compareVersions,
+  configuredManifestUrl,
   defaultTargets,
   installBundled,
   installManifest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.474",
+  "version": "0.1.476",
   "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.1",
+  "version": "1.1.7",
   "consentVersion": 2,
-  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.1",
+  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.7",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "22e9969792deb664cc40dfa32a748507e934646f70022327ecee83e297dfc5bc"
+      "sha256": "ad86c448a5296a60ec1e4f974d941e6374f1863141d6b2dfbce11edca821cefa"
     },
     {
       "path": "agents/openai.yaml",
@@ -15,11 +15,11 @@
     },
     {
       "path": "scripts/relay-protocol.mjs",
-      "sha256": "d24f4aa4991add43763753c4fec9cbc61f300fc8052e11b348287698cd35cec5"
+      "sha256": "7077b7ce084705efc02314cd71dbf29495e274db7306ac9925794178fc2da86c"
     },
     {
       "path": "scripts/relay-local.mjs",
-      "sha256": "9cfd1f25ffc20e3c6bd1ba91a71b18311655fa1ba97958053a32b0c48318d5b8"
+      "sha256": "ee2687c5f060488dd292088c8197544e7b3354e2f7cbd5d5dffaed924aa955c9"
     },
     {
       "path": "scripts/relay-attachments.mjs",

package/skill/relay/SKILL.md

@@ -1,17 +1,45 @@
 ---
 name: relay
-description: Use Relay from Claude Code or Codex over Relay's authenticated HTTPS protocol. Use when the person asks to set up Relay, read or send a Relay, check messages, reply to a contact, share their invite link, or continue the first-run Relay tutorial. Use the command helper for this setup; retain existing hosted integrations.
+description: Use Relay from Claude Code or Codex with Companion's local MCP tools and the protocol helper for setup and fallback. Use when the person asks to set up Relay, read or send a Relay, check messages, reply to a contact, share their invite link, or continue the first-run Relay tutorial. Preserve existing integrations.
 ---
 
 # Relay
 
 Use Relay inside the current agent conversation. Companion supplies a visual
-view and, once connected, owns the credentials, encryption and outgoing queue.
+view and, once connected, manages its credentials, encryption and outgoing queue.
 Hosted/headless agents can use the authenticated HTTPS protocol directly.
 
+## Agent transport
+
+<!-- BEGIN GENERATED RELAY TRANSPORT -->
+Use the available Relay MCP tools first when they answer. If they are absent or fail with an authentication or transport error, use the installed skill's protocol helper without repeatedly retrying MCP. Keep the exact approved message and idempotency key when switching transport. Do not treat permission refusals, invalid requests, account mismatches or encryption requirements as connection failures. The helper prefers the matching Companion and retains browser-approved HTTPS access for fallback. New setup uses the pinned helper immediately while Companion installs and registers local MCP for later sessions; registering MCP does not prove it is available in an already-open session. Existing hooks are preserved and new users receive no hooks.
+<!-- END GENERATED RELAY TRANSPORT -->
+
+## Keep the new user informed
+
+Use ELI5 communication throughout setup and the first Relay: write for a capable person who is new to Relay. Explain what Relay lets them do, what is happening now, and the one next action they need to take. Use short, natural sentences and familiar words. Avoid jargon, childish analogies, command inventories and step-by-step tool narration. These rules are self-contained; if an ELI5 skill is already available, apply it too, but do not require the human to install another skill.
+
+If new setup is needed, give a brief orientation before asking to set up: Relay lets them message people from their AI, and Companion gives them a visual view of their conversations. Explain that setup connects this AI to their Relay account and installs Relay's instructions and Companion with their permission. Keep access permissions and other decision-changing facts clear; plain language must not hide what they are approving.
+
+For questions, choices and approvals, prefer the current host's built-in user-question interface over a question buried in ordinary chat text, when that tool is exposed and permitted for this kind of question in the current mode. Use the actual available tool and its documented constraints; do not invent a tool or change modes to obtain one. Ask one clear decision at a time, with concise choices including 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. If the interface cannot support the question, ask it 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.
+
+During setup, give brief updates at meaningful changes or when the person needs to act. Explain delays or failures by their effect and the next step. Keep commands, paths, versions, authentication mechanics and diagnostic logs in tool work or optional detail unless they change a decision. Preserve material limitations: being connected here, Companion still installing, and another AI not yet verified are different states. Do not claim all setup is complete from partial success.
+
+After new setup, finish with what the person can do now, any remaining action or limitation, and the copyable block for their other AI. For a contact-only invitation, simply report the contact result and any next action. Teach everyday use with a short natural-language example such as “Ask me to check your Relay inbox.” 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.
+
+## Check for Relay before starting setup
+
+A pasted invitation may be a request to add a contact from someone who already uses Relay. Before asking to install anything, make read-only checks in the current environment: look for an available Relay integration, the relay executable on PATH, an installed Relay skill and its supported helper, or an existing Companion installation. Do not install or update software merely to check whether it exists, and never inspect credential-file contents.
+
+When the existing protocol helper is available, run its status command, then request GET /v1/me through that same helper to verify the live account. Status alone describes saved local state; it does not prove the connection works. An existing hosted integration can supply an equivalent read-only account check. Keep hosted integrations intact. Missing skill discovery, a command absent from PATH, a stopped Companion, expired authorization, a network failure, or a different local/remote environment does not prove Relay is uninstalled. Preserve what is installed; explain the specific issue and resolve the account or environment with the human before replacing any connection. Reopen an installed Companion when needed instead of installing it again.
+
+If Relay is already installed or connected, treat this as contact-only unless the human explicitly asks for more setup. Use the invitation's contact page in the person's usual browser: append /contact to its /i/{token} URL. The invitation document supplies the exact link. Explain that accepting adds both people to each other's contacts without sending a message. Have the human check that the browser shows the same Relay account they use in their AI and choose Add contact. If the browser is signed out, sign in to the existing account. Use a supported system-browser opener; if unavailable, show the exact contact URL in a plain-text code block for the human to copy into their usual browser. Do not open sign-in in an AI-controlled browser. Do not request a new agent authorization, replace credentials, reinstall Companion, update or reinstall skills, or repeat the first-message tutorial just to accept another invite.
+
+The contact page confirms connected, already connected, or own-invite results only after redemption succeeds. Do not claim a contact was added just because the page opened or a name-only contact search matched. If the result is unavailable or ambiguous, report that and verify before claiming success. Opening one's own invite adds no contact. Finish with the contact result; a separate message requires the human's explicit approval. Only continue into new setup when it is actually needed and authorized. If the installation state is uncertain, ask whether the person already uses Relay rather than assuming a fresh install.
+
 ## Connect
 
-If setup has not been completed, ask once:
+Only when the checks above establish that new setup is needed, ask once:
 
 > May I set up Relay, install its agent skill, keep that skill updated, and
 > install the Relay Companion in the background?
@@ -42,10 +70,9 @@ credential. If direct invocation is ever required, resolve `RELAY_SKILL_ROOT`
 to the absolute directory containing this loaded `SKILL.md` and invoke
 `node "<RELAY_SKILL_ROOT>/scripts/relay-protocol.mjs" ...`; never assume the
 current working directory is the skill directory. The helper reads an
-owner-only credential file and never prints the access token. Do not configure
-an MCP server or install a hook.
+owner-only credential file and never prints the access token. The background Companion installer registers local MCP. Do not add hooks or configure a hosted MCP server.
 
-Once per new agent session, quietly run `relay skill update` only if the `relay`
+Except for contact-only invitations, once per new agent session, quietly run `relay skill update` only if the `relay`
 executable is already available on `PATH`. If it is unavailable, skip the check
 without installing anything or interrupting the task. Continue with the
 installed skill if the network check fails. If Relay reports locally modified
@@ -53,6 +80,26 @@ files, preserve them and tell the person; never overwrite them. If it reports a
 new consent version, explain the material change and ask before running
 `relay skill update --renew-consent`.
 
+### Open approval in the person's normal browser
+
+On a local desktop, open the returned approvalUrl in the operating system's default browser using a supported external-browser action or OS URL opener. Do not use an AI-controlled browser, embedded preview, isolated browser profile, or browser automation for sign-in. Pass the exact URL as data to the opener, with safe argument handling; never interpolate it into executable shell text. On Windows, keep any launcher process hidden. Leave sign-in and approval to the human.
+
+Tell the human: “Approve Relay in your usual browser, where you normally sign in.” If a normal-browser opener is unavailable or this is a remote/headless environment, show the exact approvalUrl in a plain-text code block and say: “Copy this URL into your usual browser to approve Relay, then return here.” Keep its full fragment intact. Use this copyable fallback if opening fails or lands in the wrong browser; a clickable chat link alone may reopen the AI browser. Never claim the browser opened or approval succeeded without evidence.
+
+## Give the human a block for another AI
+
+After verifying the connection and attempting setup, include a copyable plain-text block in the completion response, even if the human skips or declines the first-message tutorial. This is an optional way to start using Relay in another AI, not a prerequisite for finishing here or a workaround for skill discovery. Do not paste it into another conversation yourself.
+
+Use the human's own reusable invitation from the helper's safe invite.url result or protocol invite-link. Never substitute the original inviter's link, invent a URL, or include credentials, pending-authorization data, or the one-time approval URL. Replace <my own Relay invite URL> below with that verified link. If it cannot be retrieved, report that limitation and give the block with the URL sentence omitted; do not delay the working connection or claim another surface is already connected.
+
+Introduce it with: “To use Relay in another AI, paste this there:”
+
+```text
+I already use Relay. Help me use the same Relay account in this AI too.
+My own Relay invite URL is: <my own Relay invite URL>
+Read the current Relay agent guide at https://sendrelays.com/llm_guide.md and the agent instructions linked from my invitation if provided. First check for an existing Relay connection on this device using the supported helper's status command; preserve a working connection and verify it is my intended account. Ask before installing or updating the skill for this AI. If this environment needs a new connection, guide me through setup with my existing account in my usual browser. Never copy credentials between environments. Do not send a message or repeat the first-message tutorial. Verify what works here.
+```
+
 ## Verify skill activation after setup
 
 Own activation under the setup permission already given. Follow the activation
@@ -110,6 +157,11 @@ After the send succeeds:
 5. Offer their reusable `invite-link` for sharing. It connects new people and
    contains no prewritten message. Do not send the link to anyone yourself.
 
+After the tutorial finishes or the person skips it, check the pinned Companion's
+`background-status` once if background installation was started. Report whether
+installation succeeded, is still running, or failed; keep the working helper
+available. Installation success does not prove MCP is active in this session.
+
 The tutorial activation event is the approved first Relay, not app installation.
 
 ## Everyday Relay work
@@ -119,9 +171,8 @@ 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.
 
-Keep the human payload natural, self-contained, and short. Put technical detail,
-file names, identifiers, evidence, and continuation instructions in the agent
-payload. Preserve exact text when the person asks for a verbatim payload.
+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.
 
 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`
@@ -137,6 +188,120 @@ 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>`
@@ -155,8 +320,16 @@ Use `attachment <relay-id> <attachment-id>` for an authorized download URL or
 locally decrypted file path. Download URLs are private, temporary transport.
 
 The same helper automatically uses Companion once it answers as the approved
-account and environment. It then removes the standalone token. If Companion
-stops after this handoff, reopen it; do not bypass its encryption with HTTPS.
+account and environment. It retains the browser-approved direct credential in
+the protected credential file. If Companion is unavailable or its authentication
+fails, the helper can use direct HTTPS after verifying the same account and that
+the service's encryption mode is off. It never bypasses account mismatches,
+permission refusals or encryption requirements. A lost send response retries
+the same body and idempotency key; never create a second send to change transport.
+Local destinations, delivery and outbox operations still require Companion.
+If an older helper already deleted the direct credential, reopen Companion or
+renew browser approval to restore direct fallback. Expired or revoked direct
+authorization also requires renewed approval; never expose or copy a token.
 `outbox` reports queued sends and failures. `outbox retry <idempotency-key>`
 retries the stored, previously approved payload with the same key when asked.
 Queued means held on this device,

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

@@ -29,6 +29,8 @@ export function readLocalDescriptor(file = localDescriptorPath()) {
 export function localRequest(descriptor, request, { timeoutMs = 30000 } = {}) {
   return new Promise((resolve, reject) => {
     const socket = net.createConnection(descriptor.endpoint);
+    let possiblySent = false;
+    const transportError = (message) => Object.assign(new Error(message), { localTransportFailure: true, possiblySent });
     let bytes = 0;
     const chunks = [];
     let finished = false;
@@ -39,8 +41,11 @@ export function localRequest(descriptor, request, { timeoutMs = 30000 } = {}) {
       socket.destroy();
       error ? reject(error) : resolve(value);
     };
-    const timer = setTimeout(() => finish(new Error("Companion did not confirm the request. Retry with the same idempotency key.")), timeoutMs);
-    socket.once("connect", () => socket.write(JSON.stringify({ ...request, capability: descriptor.capability }) + "\n"));
+    const timer = setTimeout(() => finish(transportError("Companion did not confirm the request. Retry with the same idempotency key.")), timeoutMs);
+    socket.once("connect", () => {
+      possiblySent = true;
+      socket.write(JSON.stringify({ ...request, capability: descriptor.capability }) + "\n");
+    });
     socket.on("data", (chunk) => {
       bytes += chunk.length;
       if (bytes > LOCAL_MAX_BYTES) return finish(new Error("Relay's local response is too large."));
@@ -53,7 +58,7 @@ export function localRequest(descriptor, request, { timeoutMs = 30000 } = {}) {
         } catch (error) { finish(error); }
       }
     });
-    socket.once("error", () => finish(new Error("Companion is unavailable. Reopen Relay and retry; your agent conversation can stay open.")));
-    socket.once("end", () => { if (!finished) finish(new Error("Companion closed before confirming the request. Retry with the same idempotency key.")); });
+    socket.once("error", () => finish(transportError("Companion is unavailable. Reopen Relay and retry; your agent conversation can stay open.")));
+    socket.once("end", () => { if (!finished) finish(transportError("Companion closed before confirming the request. Retry with the same idempotency key.")); });
   });
 }

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

@@ -23,6 +23,7 @@ const SAFE_GET = [
   /^\/v1\/chats\/[A-Za-z0-9_-]+$/,
   /^\/v1\/relays\/[A-Za-z0-9_-]+\/attachments\/[A-Za-z0-9_-]+\/download-url$/,
   /^\/v1\/me$/,
+  /^\/v1\/e2ee\/status$/,
   /^\/v1\/inbox(?:\?.*)?$/,
   /^\/v1\/sent(?:\?.*)?$/,
   /^\/v1\/contacts\/search\?q=.+$/,
@@ -37,11 +38,11 @@ const SAFE_POST = [
 ];
 
 function configPath(env = process.env) {
-  return env.RELAY_AGENT_CONFIG || DEFAULT_CONFIG;
+  return env.RELAY_AGENT_CONFIG || (env.RELAY_CONFIG_DIR ? path.join(env.RELAY_CONFIG_DIR, "agent-protocol.json") : DEFAULT_CONFIG);
 }
 
 function pendingPath(env = process.env) {
-  return env.RELAY_AGENT_AUTHORIZATION || DEFAULT_PENDING;
+  return env.RELAY_AGENT_AUTHORIZATION || (env.RELAY_CONFIG_DIR ? path.join(env.RELAY_CONFIG_DIR, "agent-authorization.json") : DEFAULT_PENDING);
 }
 
 function relayApiOrigin(value, env = process.env) {
@@ -75,8 +76,14 @@ function readConfig(file = configPath()) {
   let value;
   try { value = JSON.parse(fs.readFileSync(file, "utf8")); }
   catch (error) {
-    if (error?.code === "ENOENT") throw new Error("Relay is not connected in this agent yet. Complete the browser approval first.");
-    throw new Error("Relay's agent credential file could not be read.");
+    if (error?.code === "ENOENT") {
+      const local = readLocalDescriptor();
+      if (!local) throw new Error("Relay is not connected in this agent yet. Complete the browser approval first.");
+      if (!/^usr_[A-Za-z0-9_-]+$/.test(String(local.accountId || ""))) throw new Error("Relay's local account is invalid. Reopen Companion.");
+      value = { local: true, consentVersion: 2, apiUrl: local.apiUrl, account: { relayUserId: local.accountId } };
+    } else {
+      throw new Error("Relay's agent credential file could not be read.");
+    }
   }
   const apiUrl = relayApiOrigin(value?.apiUrl);
   const accessToken = String(value?.accessToken || "");
@@ -166,13 +173,31 @@ async function request(method, requestPath, body) {
   const local = readLocalDescriptor();
   if (local && (config.consentVersion ?? 1) >= 2) {
     if (local.accountId !== config.account?.relayUserId || local.apiUrl !== config.apiUrl) throw new Error("Companion is connected to a different Relay account or environment. Nothing was sent or read.");
-    const result = await localRequest(local, { method: verb, path: cleanPath, body, accountId: config.account.relayUserId });
-    // Only retire the standalone credential after the daemon has answered as
-    // the exact account. Future failures must not bypass local encryption.
-    if (!config.local) { config.local = true; delete config.accessToken; atomicWrite(configPath(), config); }
-    return result;
+    // Retain the browser-approved credential independently of Companion. Record
+    // the local attempt before dispatch so a lost response still requires the
+    // encryption/account checks on a later direct retry.
+    if (!config.local) { config.local = true; atomicWrite(configPath(), config); }
+    try {
+      return await localRequest(local, { method: verb, path: cleanPath, body, accountId: config.account.relayUserId });
+    } catch (error) {
+      const stableMutation = typeof body?.idempotencyKey === "string" && body.idempotencyKey.trim().length >= 8;
+      // Permission and application refusals are authoritative; an expired local
+      // authentication can use the separately approved direct credential.
+      // An uncertain mutation can only cross transports with the same body
+      // and stable deduplication key.
+      if ((!error.localTransportFailure && error.status !== 401) || (error.possiblySent && verb !== "GET" && !stableMutation)) throw error;
+    }
+  }
+  if (!config.accessToken.startsWith("web_") || config.accessToken.length < 20) {
+    throw new Error("This connection has no direct Relay credential. Reopen Relay Companion, or renew browser approval to enable direct fallback.");
+  }
+  if (config.expiresAt && Date.parse(config.expiresAt) <= Date.now()) throw new Error("Relay's direct authorization expired. Renew browser approval to use direct fallback.");
+  if (config.local) {
+    const me = await authenticatedRequest(config.apiUrl, config.accessToken, "GET", "/v1/me");
+    if (!config.account?.relayUserId || me.user?.id !== config.account.relayUserId) throw new Error("Direct Relay is connected to a different account. Nothing was sent or read.");
+    const encryption = await authenticatedRequest(config.apiUrl, config.accessToken, "GET", "/v1/e2ee/status");
+    if (encryption.mode !== "off") throw new Error("Reopen Relay Companion for this connection's encryption. Direct fallback is unavailable.");
   }
-  if (config.local) throw new Error("Reopen Relay Companion to use this connection. No agent restart is needed.");
   try { return await authenticatedRequest(config.apiUrl, config.accessToken, verb, cleanPath, body); }
   catch (error) {
     if (verb !== "POST" || cleanPath !== "/v1/relays" || body?.longForHumanConfirmed !== true || error.code !== "human_message_review_required" || !error.body?.reviewToken) throw error;