relay-companion 0.1.0

package/src/client.js

@@ -0,0 +1,168 @@
+import { apiUrl, deviceToken } from "./config.js";
+
+/** Thin authenticated client for relay-api, used by the CLI, MCP server, and daemon. */
+export class RelayClient {
+  constructor({ url = apiUrl(), token = deviceToken() } = {}) {
+    this.url = url.replace(/\/$/, "");
+    this.token = token;
+  }
+
+  async #req(method, path, body, { auth = true } = {}) {
+    const headers = { "Content-Type": "application/json" };
+    if (auth && this.token) headers.Authorization = `Bearer ${this.token}`;
+    const res = await fetch(`${this.url}${path}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : {};
+    if (!res.ok) {
+      const err = new Error(data.message || data.error || `HTTP ${res.status}`);
+      err.status = res.status;
+      err.body = data;
+      throw err;
+    }
+    return data;
+  }
+
+  me() {
+    return this.#req("GET", "/v1/me");
+  }
+
+  registerDevice({ pairingCode, name, platform }) {
+    return this.#req("POST", "/v1/devices/register", { pairingCode, name, platform }, { auth: false });
+  }
+
+  createTask(payload) {
+    return this.#req("POST", "/v1/tasks", payload);
+  }
+
+  listTasks() {
+    return this.#req("GET", "/v1/tasks");
+  }
+
+  listRelays() {
+    return this.#req("GET", "/v1/task-relays");
+  }
+
+  createFileUpload(payload) {
+    return this.#req("POST", "/v1/files", payload);
+  }
+
+  fileDownload(fileId) {
+    return this.#req("GET", `/v1/files/${encodeURIComponent(fileId)}/download`);
+  }
+
+  openTaskInvitation(token) {
+    return this.#req("GET", `/v1/task-invitations/${encodeURIComponent(token)}`, undefined, { auth: false });
+  }
+
+  bindTaskInvitation(token, payload = {}) {
+    return this.#req("POST", "/v1/task-invitations/bind", { token, ...payload });
+  }
+
+  getTask(taskId) {
+    return this.#req("GET", `/v1/tasks/${encodeURIComponent(taskId)}`);
+  }
+
+  acceptTask(taskId, participantId, payload) {
+    return this.#req(
+      "POST",
+      `/v1/tasks/${encodeURIComponent(taskId)}/invitations/${encodeURIComponent(participantId)}/accept`,
+      payload,
+    );
+  }
+
+  rejectTask(taskId, participantId, payload) {
+    return this.#req(
+      "POST",
+      `/v1/tasks/${encodeURIComponent(taskId)}/invitations/${encodeURIComponent(participantId)}/reject`,
+      payload,
+    );
+  }
+
+  createTaskMessage(taskId, payload) {
+    return this.#req("POST", `/v1/tasks/${encodeURIComponent(taskId)}/messages`, payload);
+  }
+
+  answerHumanQuestion(taskId, messageId, payload) {
+    return this.#req(
+      "POST",
+      `/v1/tasks/${encodeURIComponent(taskId)}/messages/${encodeURIComponent(messageId)}/human-response`,
+      payload,
+    );
+  }
+
+  approveShare(taskId, approvalId, payload) {
+    return this.#req(
+      "POST",
+      `/v1/tasks/${encodeURIComponent(taskId)}/approvals/${encodeURIComponent(approvalId)}/approve`,
+      payload,
+    );
+  }
+
+  declineShare(taskId, approvalId, payload) {
+    return this.#req(
+      "POST",
+      `/v1/tasks/${encodeURIComponent(taskId)}/approvals/${encodeURIComponent(approvalId)}/decline`,
+      payload,
+    );
+  }
+
+  completeTask(taskId, payload) {
+    return this.#req("POST", `/v1/tasks/${encodeURIComponent(taskId)}/results`, payload);
+  }
+
+  taskEvents(taskId) {
+    return this.#req("GET", `/v1/tasks/${encodeURIComponent(taskId)}/events`);
+  }
+
+  agentInbox() {
+    return this.#req("GET", "/v1/tasks/agent-inbox");
+  }
+
+  heartbeatSession(sessionId, payload) {
+    return this.#req("POST", `/v1/task-agent-sessions/${encodeURIComponent(sessionId)}/heartbeat`, payload);
+  }
+
+  postDaemonEvent(taskId, payload) {
+    return this.#req("POST", `/v1/tasks/${encodeURIComponent(taskId)}/daemon-events`, payload);
+  }
+
+  listConnectors() {
+    return this.#req("GET", "/v1/connectors");
+  }
+
+  toolCatalog() {
+    return this.#req("GET", "/v1/tools/catalog");
+  }
+
+  requestToolApproval(payload) {
+    return this.#req("POST", "/v1/tools/approvals", payload);
+  }
+
+  callTool(payload) {
+    return this.#req("POST", "/v1/tools/call", payload);
+  }
+
+  searchContacts(q) {
+    return this.#req("GET", `/v1/contacts/search?q=${encodeURIComponent(q)}`);
+  }
+
+  listContacts() {
+    return this.#req("GET", "/v1/contacts");
+  }
+
+  upsertContact({ name, email, emails }) {
+    return this.#req("POST", "/v1/contacts", { name, email, emails });
+  }
+
+  updateContact(contactId, { name, email, emails } = {}) {
+    return this.#req("PATCH", `/v1/contacts/${encodeURIComponent(contactId)}`, { name, email, emails });
+  }
+
+  importContacts(contacts, source = "imported") {
+    return this.#req("POST", "/v1/contacts/import", { contacts, source });
+  }
+}

package/src/codex-app-server.js

@@ -0,0 +1,120 @@
+// Codex `app-server` JSON-RPC client. Ported verbatim from
+// granular/tools/relay-companion/src/codex-app-server.js (require -> import only).
+// Drives thread/start, thread/name/set, thread/read against a short-lived
+// `codex app-server` process so a Relay row becomes a real native Codex thread.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import readline from "node:readline";
+
+export class CodexAppServerClient {
+  constructor({ command = defaultCodexCommand(), args = ["app-server"], cwd = process.cwd() } = {}) {
+    this.command = command;
+    this.args = args;
+    this.cwd = cwd;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.notifications = [];
+    this.proc = null;
+  }
+
+  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) => {
+      if (process.env.RELAY_DEBUG) process.stderr.write(chunk);
+    });
+    this.proc.on("error", (error) => {
+      for (const { reject } of this.pending.values()) reject(error);
+      this.pending.clear();
+      this.proc = null;
+    });
+    readline.createInterface({ input: this.proc.stdout, crlfDelay: Infinity }).on("line", (line) => {
+      if (!line.trim()) return;
+      const message = JSON.parse(line);
+      if (message.id != null && this.pending.has(message.id)) {
+        const { resolve, reject } = this.pending.get(message.id);
+        this.pending.delete(message.id);
+        if (message.error) reject(new Error(message.error.message || JSON.stringify(message.error)));
+        else resolve(message.result);
+      } else {
+        this.notifications.push(message);
+      }
+    });
+    this.proc.on("exit", (code, signal) => {
+      const error = new Error(`codex app-server exited with ${signal || code}`);
+      for (const { reject } of this.pending.values()) reject(error);
+      this.pending.clear();
+      this.proc = null;
+    });
+
+    await this.request("initialize", {
+      clientInfo: {
+        name: "granular_relay_companion",
+        title: "Relay Companion",
+        version: "0.1.0",
+      },
+      capabilities: {
+        experimentalApi: true,
+        optOutNotificationMethods: ["item/agentMessage/delta", "command/exec/outputDelta", "process/outputDelta"],
+      },
+    });
+    this.notify("initialized", {});
+  }
+
+  async stop() {
+    if (!this.proc) return;
+    this.proc.kill("SIGTERM");
+    this.proc = null;
+  }
+
+  async request(method, params = {}) {
+    if (!this.proc) throw new Error("Codex app-server is not started");
+    const id = this.nextId++;
+    const payload = { method, id, params };
+    const promise = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timed out waiting for ${method}`));
+      }, Number(process.env.RELAY_APP_SERVER_TIMEOUT_MS || 60000));
+      this.pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timeout);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        },
+      });
+    });
+    this.proc.stdin.write(`${JSON.stringify(payload)}\n`);
+    return promise;
+  }
+
+  notify(method, params = {}) {
+    if (!this.proc) throw new Error("Codex app-server is not started");
+    this.proc.stdin.write(`${JSON.stringify({ method, params })}\n`);
+  }
+}
+
+export async function withCodexAppServer(fn, options = {}) {
+  const client = new CodexAppServerClient(options);
+  await client.start();
+  try {
+    return await fn(client);
+  } finally {
+    await client.stop();
+  }
+}
+
+function defaultCodexCommand() {
+  if (process.env.CODEX_CLI_PATH) return process.env.CODEX_CLI_PATH;
+  const appBundledCodex = "/Applications/Codex.app/Contents/Resources/codex";
+  if (fs.existsSync(appBundledCodex)) return appBundledCodex;
+  return "codex";
+}

package/src/codex-desktop.js

@@ -0,0 +1,276 @@
+// Codex Desktop foregrounding driver. Ported faithfully from
+// granular/tools/relay-companion/src/codex-desktop.js. Finds the running Codex
+// main process, opens (or SIGUSR1-starts) its Node inspector, and runs a
+// Runtime.evaluate -> webContents.executeJavaScript -> electronBridge expression
+// in every BrowserWindow to refresh the recents rail and navigate-to-route the
+// freshly materialized Relay thread. Logic/constants are unchanged.
+//
+// Only adaptation: the original `import WsWebSocket from "ws"` is made optional.
+// Node 22+ exposes a global WebSocket (which the original already preferred), so
+// we use that; the `ws` package is loaded lazily only as a fallback and never at
+// module-load time, so this module imports cleanly without the dependency.
+
+import { execFile } from "node:child_process";
+import http from "node:http";
+import { setTimeout as sleep } from "node:timers/promises";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const INSPECTOR_HOST = "127.0.0.1";
+const INSPECTOR_PORTS = Array.from({ length: 11 }, (_, index) => 9229 + index);
+const CODEX_MAIN_PATH = "/Applications/Codex.app/Contents/MacOS/Codex";
+
+let wsFallbackPromise = null;
+async function resolveWebSocketImpl() {
+  if (typeof WebSocket === "function") return WebSocket;
+  if (!wsFallbackPromise) {
+    wsFallbackPromise = import("ws")
+      .then((mod) => mod.default || mod.WebSocket || mod)
+      .catch(() => null);
+  }
+  const ws = await wsFallbackPromise;
+  if (!ws) throw new Error("No WebSocket implementation available (global WebSocket missing and 'ws' not installed)");
+  return ws;
+}
+
+export async function notifyCodexDesktopThread({ threadId, pinnedThreadIds = null, timeoutMs, open = false } = {}) {
+  return notifyCodexDesktopThreads({
+    threadIds: threadId ? [threadId] : [],
+    pinnedThreadIds,
+    timeoutMs,
+    openThreadId: open ? threadId : null,
+  });
+}
+
+export async function notifyCodexDesktopThreads({
+  threadIds = [],
+  pinnedThreadIds = null,
+  openThreadId = null,
+  timeoutMs = Number(process.env.RELAY_CODEX_DESKTOP_TIMEOUT_MS || 4000),
+} = {}) {
+  if (process.env.RELAY_CODEX_DESKTOP_REFRESH === "0") return { attempted: false, reason: "disabled" };
+  if (process.platform !== "darwin") return { attempted: false, reason: "not-darwin" };
+
+  const openId = String(openThreadId || "").trim() || null;
+  const ids = uniqueStrings(openId ? [...threadIds, openId] : threadIds);
+  const pinnedIds = Array.isArray(pinnedThreadIds) ? uniqueStrings(pinnedThreadIds) : null;
+  if (!ids.length && !pinnedIds && !openId) return { attempted: false, reason: "nothing-to-refresh" };
+
+  const pids = await findCodexMainPids();
+  if (!pids.length) return { attempted: true, ok: false, reason: "codex-not-running", results: [] };
+
+  const expression = buildCodexDesktopRefreshExpression({ threadIds: ids, pinnedThreadIds: pinnedIds, openThreadId: openId });
+  const results = [];
+  for (const pid of pids) {
+    try {
+      const target = await findOrStartInspectorForPid(pid, { timeoutMs });
+      if (!target) {
+        results.push({ pid, ok: false, reason: "inspector-unavailable" });
+        continue;
+      }
+      const value = await evaluateInspectorExpression(target.webSocketDebuggerUrl, expression, { timeoutMs });
+      results.push({ pid, ok: true, value });
+    } catch (error) {
+      results.push({ pid, ok: false, error: errorMessage(error) });
+    }
+  }
+
+  return { attempted: true, ok: results.some((result) => result.ok), results };
+}
+
+export function buildCodexDesktopRefreshExpression({ threadIds = [], pinnedThreadIds = null, openThreadId = null } = {}) {
+  const rendererCode = `(${async function relayRefreshCodexRenderer(payload) {
+    const hostId = "local";
+    const bridge = window.electronBridge;
+    if (!bridge?.sendMessageFromView) return { ok: false, reason: "missing-electron-bridge" };
+
+    const sent = [];
+    async function send(message) {
+      try {
+        await bridge.sendMessageFromView(message);
+        sent.push({ type: message.type, ok: true });
+      } catch (error) {
+        sent.push({ type: message.type, ok: false, error: String(error?.message || error) });
+      }
+    }
+
+    if (Array.isArray(payload.pinnedThreadIds)) {
+      await send({ type: "set-pinned-thread-ids-for-host", hostId, threadIds: payload.pinnedThreadIds });
+    }
+    if (payload.threadIds.length) {
+      await send({ type: "hydrate-pinned-threads", hostId, threadIds: payload.threadIds });
+    }
+    await send({ type: "refresh-recent-conversations-for-host", hostId });
+    for (const threadId of payload.threadIds) {
+      await send({ type: "broadcast-conversation-snapshot-for-host", hostId, conversationId: threadId });
+    }
+    if (payload.openThreadId) {
+      try {
+        window.postMessage(
+          {
+            type: "navigate-to-route",
+            path: `/hotkey-window/thread/${encodeURIComponent(String(payload.openThreadId))}`,
+          },
+          location.origin,
+        );
+        sent.push({ type: "navigate-to-route", ok: true, threadId: payload.openThreadId });
+      } catch (error) {
+        sent.push({ type: "navigate-to-route", ok: false, error: String(error?.message || error) });
+      }
+    }
+
+    return { ok: sent.some((item) => item.ok), href: location.href, openThreadId: payload.openThreadId || null, sent };
+  }.toString()})(${JSON.stringify({
+    threadIds: uniqueStrings(threadIds),
+    pinnedThreadIds,
+    openThreadId: String(openThreadId || "").trim() || null,
+  })})`;
+
+  return `(async () => {
+    const req = process.mainModule?.require || process.getBuiltinModule("module").createRequire(process.cwd() + "/");
+    const { BrowserWindow } = req("electron");
+    const code = ${JSON.stringify(rendererCode)};
+    const windows = [];
+    for (const win of BrowserWindow.getAllWindows()) {
+      if (win.isDestroyed()) continue;
+      try {
+        windows.push({
+          id: win.id,
+          visible: win.isVisible(),
+          url: win.webContents.getURL(),
+          result: await win.webContents.executeJavaScript(code, true),
+        });
+      } catch (error) {
+        windows.push({ id: win.id, ok: false, error: String(error?.message || error) });
+      }
+    }
+    return windows;
+  })()`;
+}
+
+async function findCodexMainPids() {
+  try {
+    const { stdout } = await execFileAsync("ps", ["-Ao", "pid=,command="], { timeout: 1500, maxBuffer: 1024 * 1024 });
+    return stdout
+      .split("\n")
+      .map((line) => line.trim().match(/^(\d+)\s+(.+)$/))
+      .filter(Boolean)
+      .filter((match) => match[2] === CODEX_MAIN_PATH || match[2].startsWith(`${CODEX_MAIN_PATH} `))
+      .map((match) => Number(match[1]))
+      .filter(Number.isFinite);
+  } catch {
+    return [];
+  }
+}
+
+async function findOrStartInspectorForPid(pid, { timeoutMs }) {
+  let target = await findInspectorTargetForPid(pid);
+  if (target) return target;
+
+  try {
+    process.kill(pid, "SIGUSR1");
+  } catch {
+    return null;
+  }
+
+  const deadline = Date.now() + Math.max(500, timeoutMs);
+  do {
+    await sleep(100);
+    target = await findInspectorTargetForPid(pid);
+    if (target) return target;
+  } while (Date.now() < deadline);
+  return null;
+}
+
+async function findInspectorTargetForPid(pid) {
+  for (const port of INSPECTOR_PORTS) {
+    const targets = await listInspectorTargets(port);
+    for (const target of targets) {
+      if (!target.webSocketDebuggerUrl) continue;
+      try {
+        const value = await evaluateInspectorExpression(target.webSocketDebuggerUrl, "process.pid", { timeoutMs: 800 });
+        if (value === pid) return target;
+      } catch {
+        // Try the next inspector target.
+      }
+    }
+  }
+  return null;
+}
+
+function listInspectorTargets(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: INSPECTOR_HOST, port, path: "/json/list", timeout: 300 }, (res) => {
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        body += chunk;
+      });
+      res.on("end", () => {
+        try {
+          const parsed = JSON.parse(body);
+          resolve(Array.isArray(parsed) ? parsed : []);
+        } catch {
+          resolve([]);
+        }
+      });
+    });
+    req.on("timeout", () => {
+      req.destroy();
+      resolve([]);
+    });
+    req.on("error", () => resolve([]));
+  });
+}
+
+async function evaluateInspectorExpression(webSocketDebuggerUrl, expression, { timeoutMs = 4000 } = {}) {
+  const WebSocketImpl = await resolveWebSocketImpl();
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocketImpl(webSocketDebuggerUrl);
+    const timer = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {}
+      reject(new Error("Timed out talking to Codex inspector"));
+    }, timeoutMs);
+    const pending = new Map();
+    let nextId = 1;
+
+    ws.onopen = () => {
+      const id = nextId++;
+      pending.set(id, (message) => {
+        if (message.exceptionDetails) {
+          reject(new Error(message.exceptionDetails.text || message.result?.result?.description || "Inspector evaluation failed"));
+          return;
+        }
+        resolve(message.result?.result?.value);
+      });
+      ws.send(JSON.stringify({ id, method: "Runtime.evaluate", params: { expression, awaitPromise: true, returnByValue: true } }));
+    };
+    ws.onerror = () => reject(new Error("Failed to connect to Codex inspector"));
+    ws.onmessage = (event) => {
+      let message;
+      try {
+        message = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      const handler = pending.get(message.id);
+      if (!handler) return;
+      pending.delete(message.id);
+      clearTimeout(timer);
+      try {
+        ws.close();
+      } catch {}
+      handler(message);
+    };
+  });
+}
+
+function uniqueStrings(values) {
+  return Array.from(new Set(values.map((value) => String(value || "").trim()).filter(Boolean)));
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}