relay-companion 0.1.3 → 0.1.5

package/bin/relay.js

@@ -11,8 +11,10 @@ import { writeConfig, readConfig, apiUrl, DEFAULT_API_URL, DEFAULT_WEB_URL } fro
 import { runTaskDaemon, pollTaskRuntimeOnce } from "../src/task-daemon.js";
 import { runMcpServer } from "../src/mcp.js";
 import { runSetupInstall, runUninstall } from "../src/install.js";
+import { shouldRequireLiveTools } from "../src/setup-activation.js";
 import { openRelay, openTask } from "../src/materializer.js";
 import { resetCompanionStateForAccount } from "../src/notifications.js";
+import { finishSetupOpenRelay, normalizeSetupHost, setupOpenRelayToken, setupOpenStatus } from "../src/setup-open.js";
 
 function parseFlags(argv) {
   const flags = {};
@@ -59,14 +61,35 @@ async function cmdPair(flags, { promptForDefaults = true } = {}) {
   console.log(`Paired as ${res.user.name} <${res.user.email}>. This device is now connected to Relay.`);
 }
 
+function printActivationStatus(activation) {
+  if (!activation) return;
+  if (activation.host === "Codex") {
+    if (activation.currentSessionReady) {
+      console.log("Relay tools are live in this Codex session (`relay_send` verified).");
+      return;
+    }
+    const detail = activation.reason ? ` (${activation.reason})` : "";
+    console.log(`Relay was added to Codex, but this open Codex session does not expose relay_send yet${detail}.`);
+    return;
+  }
+  if (activation.host === "Claude Code") {
+    if (activation.ok) {
+      console.log("Relay was added to Claude Code for new sessions. Existing Claude Code sessions may need their MCP tools reloaded from inside Claude.");
+    } else {
+      console.log("Relay could not verify the Claude Code MCP registration.");
+    }
+  }
+}
+
 /** Register the Relay tools into Claude Code + Codex and start the receive daemon. */
-function applyInstall() {
-  const { installed, missing, daemon, pill } = runSetupInstall();
+async function applyInstall({ requireLiveTools = false } = {}) {
+  const { installed, missing, daemon, pill, activations = [] } = await runSetupInstall();
   if (installed.length) console.log(`Added Relay to ${installed.join(" and ")} on this machine.`);
   for (const m of missing) {
     if (!/registration failed/.test(m)) console.log(`${m} was not found here, so it was skipped.`);
     else console.log(`Could not register ${m}.`);
   }
+  for (const activation of activations) printActivationStatus(activation);
   if (daemon.ok) console.log("Relay is running in the background and will start automatically when you log in.");
   else if (daemon.reason === "autostart_unsupported_platform") {
     console.log("Run `relay daemon` to receive relays (background autostart is macOS-only for now).");
@@ -75,14 +98,37 @@ function applyInstall() {
   else if (pill?.reason === "pill_runtime_missing") {
     console.log("Run `relay pill` to open the Relay pill.");
   }
-  if (installed.length) console.log("Open Claude Code or Codex and your Relay tools are ready.");
+  if (requireLiveTools && installed.length && !activations.some((activation) => activation.currentSessionReady)) {
+    throw new Error(
+      "Relay paired and installed, but this running agent session cannot call relay_send yet. Setup is not ready in the current agent.",
+    );
+  }
+  return { installed, missing, daemon, pill, activations };
 }
 
 /** Full setup: pair this device, then install the tools + daemon. */
 async function cmdSetup(flags) {
   await cmdPair(flags, { promptForDefaults: Boolean(flags.interactive) });
   console.log("");
-  applyInstall();
+  await applyInstall({ requireLiveTools: Boolean(flags["require-live-tools"]) || shouldRequireLiveTools() });
+  const token = setupOpenRelayToken(flags);
+  if (token) {
+    console.log("");
+    const host = normalizeSetupHost(flags.host || flags.in);
+    const result = await finishSetupOpenRelay({
+      token,
+      host,
+      log: (m) => process.stderr.write(`[relay] ${m}\n`),
+    });
+    const openStatus = setupOpenStatus(result.opened, openUrl);
+    if (openStatus.opened) {
+      console.log(`Opened relay ${result.relayId} in ${host === "codex" ? "Codex" : "Claude Code"}.`);
+    } else if (openStatus.url) {
+      console.log(`Relay ${result.relayId} is ready. Open this URL: ${openStatus.url}`);
+    } else {
+      console.log(`Relay ${result.relayId} is staged in the Relay pill.`);
+    }
+  }
 }
 
 /** Install the tools + daemon on a device that is already paired. */
@@ -90,7 +136,7 @@ async function cmdInstall() {
   if (!readConfig().deviceToken) {
     throw new Error("This device is not paired yet. Run `relay setup` with a pairing code first.");
   }
-  applyInstall();
+  await applyInstall({ requireLiveTools: shouldRequireLiveTools() });
 }
 
 /** Remove the Relay tools from both agents and stop the background daemon. */
@@ -251,6 +297,7 @@ async function main() {
           "",
           "Usage:",
           "  relay setup [--code CODE] [--name NAME]               Pair this machine and add Relay to Claude Code + Codex",
+          "  relay setup --code CODE --open-relay TOKEN --host codex|claude",
           "  relay setup --interactive                             Prompt for API URL and device name during setup",
           "  relay install                                         Add Relay to your agents (device already paired)",
           "  relay uninstall                                       Remove Relay from your agents and stop the daemon",

package/overlay/inbox.html

@@ -14,6 +14,7 @@
     --ink:#1f1a17; --ink-2:#2c2824;
     --muted:#7c736b; --muted-2:#9a928a; --muted-3:#b7b1a6;
     --accent:#305566; --accent-soft:rgba(48,85,102,.10);
+    --brand-anthropic:#D9704E;
     --hair:rgba(31,26,23,.07);     /* between relay/task items */
     --hair-2:rgba(31,26,23,.06);   /* between contact rows */
     --serif:'Newsreader',Georgia,serif;
@@ -62,8 +63,10 @@
     padding:0 18px; cursor:pointer;
   }
   .mark { display:block; }
-  .mark rect { fill:var(--ink); transition:fill .25s var(--settle); }
-  .card.has-unread .sq0 { fill:var(--accent); }
+  .mark rect { transition:fill .25s var(--settle); }
+  .mark rect:nth-child(1) { fill:var(--brand-anthropic); }
+  .mark rect:nth-child(2) { fill:var(--ink); }
+  .mark rect:nth-child(3) { fill:url(#relayCodexGradient); }
   .word { font-family:var(--serif); font-size:19px; font-weight:500; letter-spacing:-.01em; color:var(--ink); line-height:1; }
   .spacer { flex:1 1 auto; }
   .minimize-hint {
@@ -276,7 +279,6 @@
     height:100%; display:flex; flex-direction:column; align-items:center; justify-content:center;
     gap:11px; padding:34px 28px; text-align:center;
   }
-  .empty .mark rect { fill:var(--muted-3); }
   .empty .t1 { font-family:var(--serif); font-size:16px; color:#4f4740; }
   .empty .t2 { font-size:12.5px; color:var(--muted-2); max-width:210px; line-height:1.45; }
   .gone { display:none !important; }
@@ -387,10 +389,22 @@
 </style>
 </head>
 <body>
+  <svg width="0" height="0" viewBox="0 0 0 0" aria-hidden="true" focusable="false">
+    <defs>
+      <linearGradient id="relayCodexGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+        <stop offset="0%" stop-color="#C1C1FA"/>
+        <stop offset="16%" stop-color="#C0B1F9"/>
+        <stop offset="38%" stop-color="#7790F7"/>
+        <stop offset="58%" stop-color="#5F74F6"/>
+        <stop offset="82%" stop-color="#342CF5"/>
+        <stop offset="100%" stop-color="#3229F5"/>
+      </linearGradient>
+    </defs>
+  </svg>
   <div class="card" id="card">
     <div class="lockup" id="lockup">
       <svg class="mark" width="17" height="17" viewBox="0 0 16 16" aria-hidden="true">
-        <rect class="sq0" x="0" y="6" width="4" height="4"/>
+        <rect x="0" y="6" width="4" height="4"/>
         <rect x="6" y="6" width="4" height="4"/>
         <rect x="12" y="6" width="4" height="4"/>
       </svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Relay companion: connects local coding agents to Relay tasks, approvals, and connector tools.",
   "type": "module",
   "bin": {

package/src/client.js

@@ -74,6 +74,10 @@ export class RelayClient {
     return this.#req("GET", `/v1/open/${encodeURIComponent(token)}/packet`, undefined, { auth: false });
   }
 
+  bindOpenRelay(token) {
+    return this.#req("POST", `/v1/open/${encodeURIComponent(token)}/bind`, {});
+  }
+
   createFileUpload(payload) {
     return this.#req("POST", "/v1/files", payload);
   }

package/src/install.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
+import { activateCodexMcp, verifyClaudeMcpRegistration } from "./setup-activation.js";
 
 // Persistent install of the Relay companion into the user's local agents.
 //
@@ -175,21 +176,26 @@ export function installPillAutostart(bin = relayBinPath()) {
  * Detect Claude Code + Codex, register the Relay MCP into each present, and
  * start the receive daemon. Returns a summary for the CLI to print.
  */
-export function runSetupInstall() {
+export async function runSetupInstall() {
   const bin = resolveStableBin();
   const installed = [];
   const missing = [];
+  const activations = [];
   if (commandExists("claude")) {
-    if (installClaudeCode(bin)) installed.push("Claude Code");
-    else missing.push("Claude Code (registration failed)");
+    if (installClaudeCode(bin)) {
+      installed.push("Claude Code");
+      activations.push(verifyClaudeMcpRegistration());
+    } else missing.push("Claude Code (registration failed)");
   } else missing.push("Claude Code");
   if (commandExists("codex")) {
-    if (installCodex(bin)) installed.push("Codex");
-    else missing.push("Codex (registration failed)");
+    if (installCodex(bin)) {
+      installed.push("Codex");
+      activations.push(await activateCodexMcp());
+    } else missing.push("Codex (registration failed)");
   } else missing.push("Codex");
   const daemon = installDaemonAutostart(bin);
   const pill = installPillAutostart(bin);
-  return { installed, missing, daemon, pill };
+  return { installed, missing, daemon, pill, activations };
 }
 
 /** Remove the Relay MCP from both agents and stop/clear the background daemon. */

package/src/mcp.js

@@ -29,7 +29,22 @@ export const TOOLS = [
           type: "array",
           items: { type: "string", enum: ["codex", "claude_code", "claude_desktop", "claude_cowork"] },
         },
-        attachments: { type: "array", items: { type: "object" } },
+        attachments: {
+          type: "array",
+          description:
+            "Optional files to send with the relay. Each item must include id, name, contentType, bytes, and optionally sha256. If the recipient may not be on Relay and will receive email fallback, include contentBase64 with the exact file bytes so Relay can attach the files directly to the email; otherwise the API will reject the send instead of emailing a broken partial relay.",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              name: { type: "string" },
+              contentType: { type: "string" },
+              bytes: { type: "number" },
+              sha256: { type: "string" },
+              contentBase64: { type: "string" },
+            },
+          },
+        },
         idempotencyKey: { type: "string" },
       },
       required: ["recipient", "title", "bodyMarkdown", "idempotencyKey"],

package/src/notifications.js

@@ -453,7 +453,10 @@ export function defaultStageRelayCompanionItem(notification) {
   return stageRelayCompanionItem(notification);
 }
 
-export function stagePlainRelayItem({ item, packet, attachmentUrls = {} }, { statePath = companionStatePath() } = {}) {
+export function stagePlainRelayItem(
+  { item, packet, attachmentUrls = {} },
+  { statePath = companionStatePath(), forceUnread = false } = {},
+) {
   if (!item?.relayId) throw new Error("stagePlainRelayItem requires an inbox item with relayId");
   const state = readCompanionState(statePath);
   state.packets ||= {};
@@ -474,7 +477,8 @@ export function stagePlainRelayItem({ item, packet, attachmentUrls = {} }, { sta
     },
   };
   const contentPath = writeNotificationPacketContent({ id: item.relayId }, content, statePath);
-  const readState = existing.state === "read" || item.state === "read" ? "read" : "unread";
+  const preserveSetupUnread = existing.setupImportedUnread === true && existing.state === "unread";
+  const readState = forceUnread || preserveSetupUnread ? "unread" : existing.state === "read" || item.state === "read" ? "read" : "unread";
   const row = {
     ...existing,
     id: item.relayId,
@@ -504,6 +508,7 @@ export function stagePlainRelayItem({ item, packet, attachmentUrls = {} }, { sta
     attachmentUrls,
     materializationDeferredReason: "relay_pill",
     materializedSurfaces: existing.materializedSurfaces || { codex: false, claudeCode: false, claudeCowork: false },
+    setupImportedUnread: forceUnread || preserveSetupUnread || undefined,
   };
   state.packets[item.relayId] = row;
   writeCompanionState(statePath, state);

package/src/setup-activation.js

@@ -0,0 +1,205 @@
+import { spawn, spawnSync } from "node:child_process";
+import readline from "node:readline";
+
+const DEFAULT_TIMEOUT_MS = 12_000;
+
+export function hasMcpTool(statusResponse, serverName = "relay", toolName = "relay_send") {
+  const servers = Array.isArray(statusResponse?.data) ? statusResponse.data : [];
+  const server = servers.find((item) => item?.name === serverName);
+  if (!server) return false;
+  if (Array.isArray(server.tools)) return server.tools.some((tool) => tool?.name === toolName);
+  return Boolean(server.tools?.[toolName]);
+}
+
+export function serverNames(statusResponse) {
+  return (Array.isArray(statusResponse?.data) ? statusResponse.data : [])
+    .map((item) => item?.name)
+    .filter(Boolean);
+}
+
+export function shouldRequireLiveTools(env = process.env) {
+  return Boolean(env.CODEX_THREAD_ID || env.CLAUDECODE || env.CLAUDE_CODE_SESSION_ID);
+}
+
+class JsonlRpcClient {
+  constructor({ command = "codex", args = ["app-server", "proxy"], cwd = process.cwd(), timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    this.command = command;
+    this.args = args;
+    this.cwd = cwd;
+    this.timeoutMs = timeoutMs;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.proc = null;
+    this.stderr = "";
+  }
+
+  async start() {
+    if (this.proc) return;
+    this.proc = spawn(this.command, this.args, {
+      cwd: this.cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env },
+    });
+    this.proc.stderr.on("data", (chunk) => {
+      this.stderr += chunk.toString();
+    });
+    this.proc.on("error", (error) => {
+      this.rejectAll(error);
+      this.proc = null;
+    });
+    this.proc.on("exit", (code, signal) => {
+      const exitLabel = signal || (code ?? "unknown");
+      const err = new Error(`codex app-server proxy exited (${exitLabel})`);
+      if (this.stderr.trim()) err.stderr = this.stderr.trim();
+      this.rejectAll(err);
+      this.proc = null;
+    });
+    readline.createInterface({ input: this.proc.stdout, crlfDelay: Infinity }).on("line", (line) => {
+      if (!line.trim()) return;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        return;
+      }
+      if (message.id == null || !this.pending.has(message.id)) return;
+      const pending = this.pending.get(message.id);
+      this.pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error) {
+        const err = new Error(message.error.message || `${pending.method} failed`);
+        err.code = message.error.code;
+        err.data = message.error.data;
+        pending.reject(err);
+      } else {
+        pending.resolve(message.result ?? {});
+      }
+    });
+  }
+
+  rejectAll(error) {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  request(method, params = undefined, timeoutMs = this.timeoutMs) {
+    if (!this.proc) return Promise.reject(new Error("codex app-server proxy is not running"));
+    const id = this.nextId++;
+    const payload = params === undefined ? { method, id } : { method, id, params };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${method} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, { method, resolve, reject, timer });
+      this.proc.stdin.write(`${JSON.stringify(payload)}\n`);
+    });
+  }
+
+  notify(method, params = {}) {
+    if (!this.proc) throw new Error("codex app-server proxy is not running");
+    this.proc.stdin.write(`${JSON.stringify({ method, params })}\n`);
+  }
+
+  async stop() {
+    if (!this.proc) return;
+    this.proc.kill("SIGTERM");
+    this.proc = null;
+  }
+}
+
+function classifyCodexActivationError(error) {
+  const text = `${error?.message || ""}\n${error?.stderr || ""}\n${error?.data ? JSON.stringify(error.data) : ""}`;
+  if (/app-server-control|control socket|No such file|not running|missing/i.test(text)) {
+    return "codex_control_socket_unavailable";
+  }
+  if (/experimentalApi/i.test(text)) return "codex_experimental_api_rejected";
+  return "codex_reload_failed";
+}
+
+export async function activateCodexMcp({
+  client = null,
+  command = "codex",
+  cwd = process.cwd(),
+  threadId = process.env.CODEX_THREAD_ID,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const rpc = client || new JsonlRpcClient({ command, cwd, timeoutMs });
+  try {
+    await rpc.start();
+    await rpc.request("initialize", {
+      clientInfo: {
+        name: "relay_setup",
+        title: "Relay Setup",
+        version: "0.1.0",
+      },
+      capabilities: {
+        experimentalApi: true,
+        optOutNotificationMethods: ["item/agentMessage/delta", "command/exec/outputDelta", "process/outputDelta"],
+      },
+    }, timeoutMs);
+    rpc.notify("initialized", {});
+    await rpc.request("config/mcpServer/reload", null, timeoutMs);
+
+    const deadline = Date.now() + timeoutMs;
+    let lastStatus = null;
+    do {
+      lastStatus = await rpc.request("mcpServerStatus/list", {
+        detail: "toolsAndAuthOnly",
+        limit: 100,
+        ...(threadId ? { threadId } : {}),
+      }, timeoutMs);
+      if (hasMcpTool(lastStatus)) {
+        return {
+          host: "Codex",
+          ok: true,
+          currentSessionReady: true,
+          reason: "relay_send_verified",
+          verifiedTool: "relay_send",
+        };
+      }
+      await new Promise((resolve) => setTimeout(resolve, 300));
+    } while (Date.now() < deadline);
+
+    return {
+      host: "Codex",
+      ok: false,
+      currentSessionReady: false,
+      reason: "relay_send_not_listed",
+      serverNames: serverNames(lastStatus),
+    };
+  } catch (error) {
+    return {
+      host: "Codex",
+      ok: false,
+      currentSessionReady: false,
+      reason: classifyCodexActivationError(error),
+      detail: error?.stderr || error?.message || String(error),
+    };
+  } finally {
+    await rpc.stop?.();
+  }
+}
+
+export function verifyClaudeMcpRegistration({ runCommand, command = "claude" } = {}) {
+  const run = runCommand || ((cmd, args) => spawnSyncCompat(cmd, args));
+  const res = run(command, ["mcp", "get", "relay"]);
+  return {
+    host: "Claude Code",
+    ok: Boolean(res.ok),
+    currentSessionReady: false,
+    reason: res.ok ? "registered_for_new_sessions" : "registration_not_visible",
+    detail: res.out || "",
+  };
+}
+
+function spawnSyncCompat(cmd, args) {
+  const res = spawnSync(cmd, args, { encoding: "utf8", timeout: 10_000 });
+  return {
+    ok: !res.error && res.status === 0,
+    out: `${res.stdout || ""}${res.stderr || ""}`.trim(),
+  };
+}

package/src/setup-open.js

@@ -0,0 +1,83 @@
+import { RelayClient } from "./client.js";
+import { openRelay } from "./materializer.js";
+import { stagePlainRelayItem } from "./notifications.js";
+
+export function normalizeSetupHost(host) {
+  const clean = String(host || "").trim().toLowerCase();
+  return clean === "codex" ? "codex" : "claude";
+}
+
+export function setupOpenRelayToken(flags = {}) {
+  return String(flags["open-relay"] || flags.openRelay || flags.relay || "").trim() || null;
+}
+
+export function setupOpenStatus(opened, openUrlFn = () => false) {
+  if (!opened) return { opened: false, fallbackAttempted: false, url: null };
+  if (opened.openedInHost || opened.skipExternalOpen) {
+    return { opened: true, fallbackAttempted: false, url: opened.url || null };
+  }
+  if (!opened.url) return { opened: false, fallbackAttempted: false, url: null };
+  return { opened: Boolean(openUrlFn(opened.url)), fallbackAttempted: true, url: opened.url };
+}
+
+
+function inboxItemFromOpenRelay(relay) {
+  return {
+    relayId: relay.relayId,
+    state: "delivered",
+    createdAt: relay.createdAt,
+    updatedAt: relay.createdAt,
+    kind: relay.kind,
+    title: relay.title,
+    displayTitle: relay.title,
+    sender: relay.sender,
+    preview: relay.preview,
+    hasAttachments: Boolean(relay.attachments?.length),
+  };
+}
+
+export async function stageCurrentInbox({ client = new RelayClient(), stage = stagePlainRelayItem, forceUnread = false, log = () => {} } = {}) {
+  const inbox = await client.inbox();
+  const staged = [];
+  for (const item of inbox.items || []) {
+    try {
+      const fetched = await client.fetchRelay(item.relayId);
+      stage({ item, packet: fetched.packet, attachmentUrls: fetched.attachmentUrls || {} }, { forceUnread });
+      staged.push(item.relayId);
+    } catch (error) {
+      log(`could not stage relay ${item.relayId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return staged;
+}
+
+export async function finishSetupOpenRelay({
+  token,
+  host = "claude",
+  client = new RelayClient(),
+  stage = stagePlainRelayItem,
+  openRelayFn = openRelay,
+  log = () => {},
+} = {}) {
+  const cleanToken = String(token || "").trim();
+  if (!cleanToken) return null;
+
+  const bound = await client.bindOpenRelay(cleanToken);
+  const relay = bound?.relay;
+  if (!relay?.relayId) {
+    throw new Error("Relay setup paired this device, but the relay link could not be attached to the account.");
+  }
+
+  const stagedIds = await stageCurrentInbox({ client, stage, forceUnread: true, log });
+  if (!stagedIds.includes(relay.relayId)) {
+    const fetched = await client.fetchRelay(relay.relayId);
+    stage({
+      item: inboxItemFromOpenRelay(relay),
+      packet: fetched.packet,
+      attachmentUrls: fetched.attachmentUrls || {},
+    }, { forceUnread: true });
+  }
+
+  const result = await openRelayFn({ id: relay.relayId, host: normalizeSetupHost(host), log });
+  return { relayId: relay.relayId, staged: true, opened: result };
+}