relay-companion 0.1.0

package/src/codex-session-writer.js

@@ -0,0 +1,170 @@
+// Codex rollout writer. Ported faithfully from
+// granular/tools/relay-companion/src/codex-session-writer.js (only the codexHome
+// import points at this package's host-paths.js). Appends a visible assistant
+// turn to a thread's .jsonl rollout and inserts the zero-width "index marker"
+// user event so Codex Desktop's default local-thread route will index the thread.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { codexHome } from "./host-paths.js";
+
+const CODEX_THREAD_INDEX_MARKER = "\u200b";
+
+export function appendVisibleAssistantTurn({
+  sessionPath,
+  text,
+  cwd = process.cwd(),
+  currentDate = isoDate(),
+  timezone = localTimezone(),
+}) {
+  if (!sessionPath) throw new Error("sessionPath is required");
+  if (!text || !String(text).trim()) throw new Error("assistant turn text is required");
+  const resolvedPath = path.resolve(sessionPath);
+  if (!fs.existsSync(resolvedPath)) throw new Error(`Codex session does not exist: ${resolvedPath}`);
+
+  const timestamp = new Date().toISOString();
+  const turnId = crypto.randomUUID();
+  const messageId = `msg_relay_${crypto.randomBytes(16).toString("hex")}`;
+  const cleanText = String(text);
+  const lineEnvelope = {
+    timestamp,
+    type: "turn_context",
+    payload: {
+      turn_id: turnId,
+      cwd,
+      workspace_roots: [cwd],
+      current_date: currentDate,
+      timezone,
+      approval_policy: "never",
+      sandbox_policy: { type: "danger-full-access" },
+      permission_profile: { type: "disabled" },
+      model: "gpt-5.5",
+      personality: "pragmatic",
+      collaboration_mode: {
+        mode: "default",
+        settings: {
+          model: "gpt-5.5",
+          reasoning_effort: "xhigh",
+          developer_instructions: null,
+        },
+      },
+      multi_agent_version: "v1",
+      realtime_active: false,
+      effort: "xhigh",
+      summary: "auto",
+    },
+  };
+  const lines = [
+    lineEnvelope,
+    {
+      timestamp,
+      type: "event_msg",
+      payload: {
+        type: "agent_message",
+        message: cleanText,
+        phase: "final_answer",
+        memory_citation: null,
+      },
+    },
+    {
+      timestamp,
+      type: "response_item",
+      payload: {
+        type: "message",
+        id: messageId,
+        role: "assistant",
+        content: [{ type: "output_text", text: cleanText }],
+        phase: "final_answer",
+        metadata: { turn_id: turnId },
+      },
+    },
+    {
+      timestamp,
+      type: "event_msg",
+      payload: {
+        type: "task_complete",
+        turn_id: turnId,
+        last_agent_message: cleanText,
+        completed_at: Math.floor(Date.now() / 1000),
+        duration_ms: 0,
+        time_to_first_token_ms: 0,
+      },
+    },
+  ];
+
+  fs.appendFileSync(resolvedPath, `${lines.map((line) => JSON.stringify(line)).join("\n")}\n`);
+  return { sessionPath: resolvedPath, turnId, messageId };
+}
+
+export function ensureCodexThreadIndexMarker({ sessionPath, markerId = "" }) {
+  if (!sessionPath) throw new Error("sessionPath is required");
+  const resolvedPath = path.resolve(sessionPath);
+  if (!fs.existsSync(resolvedPath)) throw new Error(`Codex session does not exist: ${resolvedPath}`);
+
+  const clientId = `relay_index_${safeMarkerId(markerId) || crypto.randomBytes(8).toString("hex")}`;
+  const text = fs.readFileSync(resolvedPath, "utf8");
+  if (text.includes(`"client_id":"${clientId}"`) || text.includes(`"clientId":"${clientId}"`)) {
+    return { sessionPath: resolvedPath, inserted: false, clientId };
+  }
+
+  const lines = text.trimEnd().split("\n").filter(Boolean);
+  const insertAt = lines.findIndex((line) => {
+    try {
+      return JSON.parse(line)?.type === "session_meta";
+    } catch {
+      return false;
+    }
+  });
+  // Codex Desktop's default local-thread route ignores assistant-only rollouts.
+  // This zero-width user event makes the session indexable without making the Relay body user-authored.
+  const marker = {
+    timestamp: new Date().toISOString(),
+    type: "event_msg",
+    payload: {
+      type: "user_message",
+      client_id: clientId,
+      message: CODEX_THREAD_INDEX_MARKER,
+      images: [],
+      local_images: [],
+      text_elements: [],
+      metadata: { relaySynthetic: true, indexOnly: true },
+    },
+  };
+
+  lines.splice(insertAt >= 0 ? insertAt + 1 : 0, 0, JSON.stringify(marker));
+  fs.writeFileSync(resolvedPath, `${lines.join("\n")}\n`);
+  return { sessionPath: resolvedPath, inserted: true, clientId };
+}
+
+export function findCodexSessionPath(threadId, sessionsRoot = path.join(codexHome(), "sessions")) {
+  if (!threadId || !fs.existsSync(sessionsRoot)) return null;
+  const stack = [sessionsRoot];
+  while (stack.length) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(entryPath);
+      } else if (entry.isFile() && entry.name.endsWith(`${threadId}.jsonl`)) {
+        return entryPath;
+      }
+    }
+  }
+  return null;
+}
+
+function isoDate(date = new Date()) {
+  return date.toISOString().slice(0, 10);
+}
+
+function localTimezone() {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+
+function safeMarkerId(value) {
+  return String(value || "")
+    .replace(/[^A-Za-z0-9_-]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 96);
+}

package/src/codex-state.js

@@ -0,0 +1,114 @@
+// Codex thread state writers. Ported faithfully from
+// granular/tools/relay-companion/src/codex-state.js (paths -> host-paths.js,
+// writeJsonAtomic -> host-json.js). Sets danger-full-access permissions in the
+// Codex global-state atom and writes the threads-table row (title/preview/cwd/
+// recency) into Codex's sqlite state DB so the thread shows in the recents rail.
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { codexGlobalStatePath, codexStateDbPath } from "./host-paths.js";
+import { writeJsonAtomic } from "./host-json.js";
+
+const DEFAULT_THREAD_PERMISSIONS = {
+  activePermissionProfile: { id: ":danger-full-access", extends: null },
+  approvalPolicy: "never",
+  approvalsReviewer: "user",
+  sandboxPolicy: { type: "dangerFullAccess" },
+};
+
+export function finalizeCodexThreadState({ threadId, title, cwd, preview }) {
+  if (!threadId) throw new Error("threadId is required");
+  const permissions = ensureCodexThreadPermissions(threadId);
+  const stateDb = updateCodexThreadStateDb({ threadId, title, cwd, preview });
+  return { permissions, stateDb };
+}
+
+export function ensureCodexThreadPermissions(threadId) {
+  const filePath = codexGlobalStatePath();
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const state = fs.existsSync(filePath) ? JSON.parse(fs.readFileSync(filePath, "utf8")) : {};
+  state["electron-persisted-atom-state"] ||= {};
+  state["electron-persisted-atom-state"]["heartbeat-thread-permissions-by-id"] ||= {};
+  state["electron-persisted-atom-state"]["heartbeat-thread-permissions-by-id"][threadId] ||= DEFAULT_THREAD_PERMISSIONS;
+  writeJsonAtomic(filePath, state);
+  return { attempted: true, filePath };
+}
+
+export function updateCodexThreadStateDb({ threadId, title, cwd, preview }) {
+  const dbPath = codexStateDbPath();
+  if (!fs.existsSync(dbPath)) return { attempted: false, reason: "missing-state-db", dbPath };
+  const cleanTitle = String(title || "").trim();
+  const cleanPreview = String(preview || "").trim();
+  const cleanCwd = cwd ? path.resolve(String(cwd)) : "";
+  const updates = ["updated_at = strftime('%s','now')", "updated_at_ms = CAST(strftime('%s','now') AS INTEGER) * 1000"];
+  if (cleanTitle) {
+    updates.push(`title = ${sqlString(cleanTitle)}`);
+  }
+  if (cleanPreview) {
+    updates.push(`preview = ${sqlString(cleanPreview)}`);
+  }
+  if (cleanCwd) {
+    updates.push(`cwd = ${sqlString(cleanCwd)}`);
+  }
+  updates.push("recency_at = strftime('%s','now')");
+  updates.push("recency_at_ms = CAST(strftime('%s','now') AS INTEGER) * 1000");
+
+  const sql = `UPDATE threads SET ${updates.join(", ")} WHERE id = ${sqlString(threadId)};`;
+  const result = spawnSync("sqlite3", [dbPath, sql], { encoding: "utf8", timeout: 5000 });
+  if (result.status !== 0) {
+    return {
+      attempted: true,
+      ok: false,
+      dbPath,
+      error: result.stderr || result.stdout || "sqlite3 update failed",
+    };
+  }
+  return { attempted: true, ok: true, dbPath };
+}
+
+// thread/start persists the threads row asynchronously after thread/name/set. Callers that stop a
+// short-lived app-server must wait for this row before handing the thread id to the desktop app.
+export function codexThreadRowExists(threadId) {
+  const dbPath = codexStateDbPath();
+  if (!threadId || !fs.existsSync(dbPath)) return false;
+  const result = spawnSync("sqlite3", [dbPath, `SELECT count(*) FROM threads WHERE id = ${sqlString(threadId)};`], {
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  return result.status === 0 && String(result.stdout || "").trim() !== "0";
+}
+
+// Cloud-row adapter: the original read packet.sender/briefingMarkdown/kind. The
+// cloud companion row carries senderName + bodyMarkdown/briefingMarkdown +
+// (optionally) kind, so derive the same preview line from whichever is present.
+export function relayThreadPreview(row) {
+  // Never surface the brand word "Relay" or the placeholder "Someone" as if it were
+  // a person; the viewer's own agent is "Your agent".
+  const rawSender = String(row.senderName || row.sender?.name || row.sender?.handle || "").trim();
+  const sender = rawSender && !/^(relay|someone)$/i.test(rawSender) ? rawSender : "Your agent";
+  const body = stripMarkdown(row.bodyMarkdown || row.briefingMarkdown || "");
+  const kind = String(row.kind || row.relayNotificationKind || "").toLowerCase();
+  const prefix = kind === "message" ? `${sender} sent this Relay message:` : `Relay from ${sender}:`;
+  return truncatePreview(`${prefix} ${body}`.trim());
+}
+
+function stripMarkdown(value) {
+  return String(value || "")
+    .replace(/^#+\s+/gm, "")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/[*_~>#-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function truncatePreview(value, maxLength = 1200) {
+  const clean = String(value || "").trim();
+  if (clean.length <= maxLength) return clean;
+  return `${clean.slice(0, maxLength - 1).trimEnd()}…`;
+}
+
+function sqlString(value) {
+  return `'${String(value ?? "").replaceAll("'", "''")}'`;
+}

package/src/config.js

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Companion configuration lives in ~/.relay/config.json. It holds the device
+ * token issued at pairing and the API base URL. Environment variables override
+ * the file so a single machine can point at a local or staging API for testing.
+ */
+export function configDir() {
+  return process.env.RELAY_CONFIG_DIR || path.join(os.homedir(), ".relay");
+}
+
+export function configPath() {
+  return path.join(configDir(), "config.json");
+}
+
+export function readConfig() {
+  try {
+    const raw = fs.readFileSync(configPath(), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(patch) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const next = { ...readConfig(), ...patch };
+  fs.writeFileSync(configPath(), JSON.stringify(next, null, 2), { mode: 0o600 });
+  return next;
+}
+
+export function apiUrl() {
+  return (
+    process.env.RELAY_API_URL ||
+    readConfig().apiUrl ||
+    "https://aia6vj5pgp.us-east-1.awsapprunner.com"
+  );
+}
+
+export function webUrl() {
+  return (
+    process.env.RELAY_WEB_URL ||
+    readConfig().webUrl ||
+    "http://localhost:3000"
+  ).replace(/\/$/, "");
+}
+
+export function deviceToken() {
+  return process.env.RELAY_DEVICE_TOKEN || readConfig().deviceToken || "";
+}
+
+export function currentUser() {
+  return readConfig().user || null;
+}
+
+/** Durable local runtime ledger for agent task sessions. */
+export function taskLedgerPath() {
+  return path.join(configDir(), "task-ledger.json");
+}

package/src/host-json.js

@@ -0,0 +1,14 @@
+// Minimal atomic JSON writer used by the lazy-open engine's host-state writers
+// (codex-state, pinning). The original relay-companion imported writeJsonAtomic
+// from its large json-store.js; here we only need the atomic write primitive, so
+// this is the adapter the port note calls for — same temp+rename behavior.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export function writeJsonAtomic(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+}

package/src/host-paths.js

@@ -0,0 +1,67 @@
+// Host filesystem paths used by the lazy-open session-materialization engine.
+//
+// Ported faithfully from granular/tools/relay-companion/src/paths.js (the subset
+// the open path needs: Codex home/state + Claude home/projects/desktop sessions).
+// Same env-var override names, same default locations, same behavior. Named
+// host-paths.js so it doesn't collide with any other path helper in this package.
+
+import os from "node:os";
+import path from "node:path";
+
+export const DEFAULT_CODEX_HOME = path.join(os.homedir(), ".codex");
+export const DEFAULT_CODEX_GLOBAL_STATE = path.join(DEFAULT_CODEX_HOME, ".codex-global-state.json");
+export const DEFAULT_CODEX_STATE_DB = path.join(DEFAULT_CODEX_HOME, "state_5.sqlite");
+export const DEFAULT_CLAUDE_HOME = path.join(os.homedir(), ".claude");
+export const DEFAULT_CLAUDE_DESKTOP_CONFIG = path.join(
+  os.homedir(),
+  "Library",
+  "Application Support",
+  "Claude",
+  "claude_desktop_config.json",
+);
+export const DEFAULT_CLAUDE_DESKTOP_SESSIONS = path.join(
+  os.homedir(),
+  "Library",
+  "Application Support",
+  "Claude",
+  "claude-code-sessions",
+);
+
+// Durable companion store dir. The cloud companion stages packets + state under
+// RELAY_HOME/RELAY_COMPANION_HOME (see notifications.companionHome()); the engine
+// writes its own snapshot copies under <store>/packets too.
+export function storeDir() {
+  return (
+    process.env.RELAY_HOME ||
+    process.env.RELAY_COMPANION_HOME ||
+    path.join(os.homedir(), ".relay-companion")
+  );
+}
+
+export function codexHome() {
+  return process.env.CODEX_HOME || DEFAULT_CODEX_HOME;
+}
+
+export function codexGlobalStatePath() {
+  return process.env.CODEX_GLOBAL_STATE || path.join(codexHome(), ".codex-global-state.json");
+}
+
+export function codexStateDbPath() {
+  return process.env.CODEX_STATE_DB || path.join(codexHome(), "state_5.sqlite");
+}
+
+export function claudeHome() {
+  return process.env.CLAUDE_HOME || DEFAULT_CLAUDE_HOME;
+}
+
+export function claudeProjectsDir() {
+  return process.env.CLAUDE_PROJECTS_DIR || path.join(claudeHome(), "projects");
+}
+
+export function claudeDesktopConfigPath() {
+  return process.env.CLAUDE_DESKTOP_CONFIG || DEFAULT_CLAUDE_DESKTOP_CONFIG;
+}
+
+export function claudeDesktopSessionsDir() {
+  return process.env.CLAUDE_DESKTOP_SESSIONS_DIR || DEFAULT_CLAUDE_DESKTOP_SESSIONS;
+}

package/src/install.js

@@ -0,0 +1,142 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Persistent install of the Relay companion into the user's local agents.
+//
+// After pairing, this registers the Relay MCP server (`relay mcp`) into Claude
+// Code and Codex at user scope, so EVERY interactive session gets the Relay
+// tools + the user's connected provider tools — not just background task runs.
+// It also installs a launchd agent that keeps the receive daemon running.
+
+const DAEMON_LAUNCH_LABEL = "work.relay.companion";
+
+export const PACKAGE_NAME = "relay-companion";
+
+/** Absolute path to this companion's CLI entrypoint (deps resolve from here). */
+export function relayBinPath() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../bin/relay.js");
+}
+
+/**
+ * A STABLE path to the companion CLI that the agents and the daemon can keep
+ * launching. When `setup` runs from npx (an ephemeral cache that gets cleaned),
+ * we global-install the package and point at that instead, so the registration
+ * doesn't rot. From a dev checkout or an existing global install the running
+ * path is already stable, so we use it directly.
+ */
+export function resolveStableBin() {
+  const here = relayBinPath();
+  const ephemeral = /[\\/](_npx|\.npm[\\/]_npx|npm-cache[\\/]_npx)[\\/]/.test(here);
+  if (!ephemeral) return here;
+  const install = run("npm", ["install", "-g", `${PACKAGE_NAME}@latest`]);
+  if (!install.ok) return here; // fall back; caller still gets a working (if cache-bound) path
+  const rootRes = spawnSync("npm", ["root", "-g"], { encoding: "utf8", timeout: 20_000 });
+  const root = (rootRes.stdout || "").trim();
+  const globalBin = path.join(root, ...PACKAGE_NAME.split("/"), "bin", "relay.js");
+  return fs.existsSync(globalBin) ? globalBin : here;
+}
+
+function run(cmd, args) {
+  const res = spawnSync(cmd, args, { encoding: "utf8", timeout: 20_000 });
+  return {
+    ok: !res.error && res.status === 0,
+    status: res.status,
+    out: `${res.stdout || ""}${res.stderr || ""}`.trim(),
+    missing: Boolean(res.error && res.error.code === "ENOENT"),
+  };
+}
+
+/** Whether an agent CLI is on PATH. */
+export function commandExists(cmd) {
+  const res = spawnSync(cmd, ["--version"], { encoding: "utf8", timeout: 8000 });
+  return !res.error && (res.status === 0 || Boolean((res.stdout || "").trim()));
+}
+
+/** Register the Relay MCP into Claude Code at user scope (loads in every session). Idempotent. */
+export function installClaudeCode(bin = relayBinPath(), node = process.execPath) {
+  run("claude", ["mcp", "remove", "-s", "user", "relay"]); // ignore if absent
+  const res = run("claude", ["mcp", "add", "-s", "user", "relay", "--", node, bin, "mcp"]);
+  return res.ok || /already exists/i.test(res.out);
+}
+
+/** Register the Relay MCP into Codex (loads in every session). Idempotent. */
+export function installCodex(bin = relayBinPath(), node = process.execPath) {
+  run("codex", ["mcp", "remove", "relay"]); // ignore if absent
+  const res = run("codex", ["mcp", "add", "relay", "--", node, bin, "mcp"]);
+  return res.ok || /already exists/i.test(res.out);
+}
+
+/** Install + load a launchd agent that keeps `relay daemon` running (macOS). Idempotent. */
+export function installDaemonAutostart(bin = relayBinPath(), node = process.execPath) {
+  if (process.platform !== "darwin") return { ok: false, reason: "autostart_unsupported_platform" };
+  const home = os.homedir();
+  const plistPath = path.join(home, "Library", "LaunchAgents", `${DAEMON_LAUNCH_LABEL}.plist`);
+  const logPath = path.join(home, ".relay", "daemon.log");
+  fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const pathEnv = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${DAEMON_LAUNCH_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${node}</string>
+    <string>${bin}</string>
+    <string>daemon</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${logPath}</string>
+  <key>StandardErrorPath</key><string>${logPath}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${pathEnv}</string>
+  </dict>
+</dict>
+</plist>
+`;
+  fs.writeFileSync(plistPath, plist);
+  run("launchctl", ["unload", plistPath]); // ignore if not loaded
+  const res = run("launchctl", ["load", plistPath]);
+  return { ok: res.ok, plistPath, logPath };
+}
+
+/**
+ * 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() {
+  const bin = resolveStableBin();
+  const installed = [];
+  const missing = [];
+  if (commandExists("claude")) {
+    if (installClaudeCode(bin)) installed.push("Claude Code");
+    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)");
+  } else missing.push("Codex");
+  const daemon = installDaemonAutostart(bin);
+  return { installed, missing, daemon };
+}
+
+/** Remove the Relay MCP from both agents and stop/clear the background daemon. */
+export function runUninstall() {
+  run("claude", ["mcp", "remove", "-s", "user", "relay"]);
+  run("codex", ["mcp", "remove", "relay"]);
+  if (process.platform === "darwin") {
+    const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${DAEMON_LAUNCH_LABEL}.plist`);
+    run("launchctl", ["unload", plistPath]);
+    try {
+      fs.unlinkSync(plistPath);
+    } catch {
+      /* already gone */
+    }
+  }
+}