relay-companion 0.1.0

package/src/materializer.js

@@ -0,0 +1,378 @@
+// Lazy-open session-materialization orchestrator.
+//
+// Ported from granular/tools/relay-companion/src/materializer.js. The HOST side
+// (createCodexThread + the codex app-server / rollout / index-marker / state-db /
+// pin / desktop-inspector sequence, and the Claude native-session forge + import
+// + title-repair) is faithful to the original. The INPUT side is adapted: instead
+// of loading an on-disk granular packet, openRelay reads the cloud companion row
+// staged in RELAY_HOME/state.json (packets.<id>) — or its snapshotted contentPath,
+// or fetches the relay body via RelayClient if only a pointer exists — and maps it.
+//
+// openRelay({ id, host, log }) returns { url, skipExternalOpen, openedInHost } so
+// the CLI prints the same contract the original cli.js did.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { materializeRowForClaude } from "./claude-materializer.js";
+import {
+  ensureClaudeDesktopImported,
+  isClaudeNativeSessionImported,
+  repairClaudeDesktopRelaySessions,
+} from "./claude-session-writer.js";
+import {
+  appendVisibleAssistantTurn,
+  ensureCodexThreadIndexMarker,
+  findCodexSessionPath,
+} from "./codex-session-writer.js";
+import { withCodexAppServer } from "./codex-app-server.js";
+import { codexThreadRowExists, finalizeCodexThreadState, relayThreadPreview } from "./codex-state.js";
+import { notifyCodexDesktopThreads } from "./codex-desktop.js";
+import { readPinnedThreadIds, setThreadPinned } from "./pinning.js";
+import { relayRowTitle, renderRelayRowBriefing, renderRelayRowSeed, renderTaskOpenBriefing } from "./relay-briefing.js";
+import { storeDir } from "./host-paths.js";
+
+function companionStatePath() {
+  return path.join(storeDir(), "state.json");
+}
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(companionStatePath(), "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+function writeStateAtomic(state) {
+  const statePath = companionStatePath();
+  fs.mkdirSync(path.dirname(statePath), { recursive: true, mode: 0o700 });
+  const tmp = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, statePath);
+}
+
+function getRowState(id) {
+  const state = readState();
+  return (state.packets && state.packets[id]) || null;
+}
+
+// Persist materialization results back onto the staged row, so a re-open reuses
+// the existing native session instead of forging a new one each click.
+function rememberRow(id, patch) {
+  const state = readState();
+  state.packets ||= {};
+  const existing = state.packets[id] || {};
+  const next = { ...existing, ...patch, updatedAt: new Date().toISOString() };
+  state.packets[id] = next;
+  writeStateAtomic(state);
+  return next;
+}
+
+// Read the snapshotted packet content (written at stage time) if present. This is
+// the durable copy that survives independently of the live row.
+function readRowContent(rowState) {
+  for (const candidate of [rowState?.contentPath, rowState?.filePath]) {
+    if (!candidate || !fs.existsSync(candidate)) continue;
+    try {
+      return JSON.parse(fs.readFileSync(candidate, "utf8"));
+    } catch {}
+  }
+  return null;
+}
+
+// Resolve the materialization input for a staged row: merge the live row with its
+// snapshotted packet content, and — when the row points at a task — fetch the
+// verified task object via the RelayClient so the per-kind seed is grounded in the
+// real API. Returns a normalized "row" the host writers consume.
+async function resolveRow(id, { log = () => {} } = {}) {
+  const rowState = getRowState(id);
+  if (!rowState) throw new Error(`Unknown Relay row: ${id}`);
+  const content = readRowContent(rowState);
+  // The staged content packet carries the same fields under different names
+  // (briefingMarkdown/displayTitle/sender). Merge so either source satisfies the
+  // host writers; the live row wins for staged metadata, content fills the body.
+  const row = {
+    ...(content || {}),
+    ...rowState,
+    id,
+    briefingMarkdown:
+      firstNonEmpty(rowState.briefingMarkdown, content?.briefingMarkdown) || "",
+    bodyMarkdown: firstNonEmpty(rowState.bodyMarkdown, content?.briefingMarkdown, content?.bodyMarkdown) || "",
+    displayTitle: firstNonEmpty(rowState.displayTitle, rowState.title, content?.displayTitle, content?.title) || "Relay",
+    title: firstNonEmpty(rowState.title, content?.title, rowState.displayTitle) || "Relay",
+    // Do NOT default to the brand word "Relay" as if it were a person. When no real
+    // sender is staged, leave it empty so the per-kind seed builders (relay-briefing)
+    // apply the correct human-facing fallback ("Your agent" for the viewer's own
+    // agent). notifications.js already resolves this to "Your agent" or a real name
+    // before staging; this is only a last-resort merge default.
+    senderName: firstNonEmpty(rowState.senderName, content?.sender?.name, content?.sender?.handle) || "",
+    attachments: rowState.attachments || content?.attachments || [],
+    delivery: content?.delivery || rowState.delivery || null,
+    sender: content?.sender || (rowState.senderName ? { name: rowState.senderName } : null),
+  };
+
+  // When the row points at a task, fetch the verified task object so the per-kind
+  // seed builder can ground the session in the real question / result / objective
+  // and recent messages — not just the thin staged pointer. Best-effort: a fetch
+  // failure leaves row.task null and the briefing falls back to staged fields.
+  if (row.taskId) {
+    const task = await fetchTask(row.taskId, { log });
+    if (task) row.task = task;
+  }
+
+  // Render the per-kind seed once for the codex thread preview and as a coherent
+  // briefingMarkdown (which prefers the row, then the verified task, then an honest
+  // minimal fallback that never crashes). IMPORTANT: do NOT overwrite row.bodyMarkdown
+  // with the rendered seed — bodyMarkdown is a RAW content source that the seed
+  // builders read back (e.g. as the human_question fallback), so clobbering it makes
+  // the next render echo the prior seed into itself (a doubled body). briefingMarkdown
+  // is preview-only and is not read back by the seed builders, so it is safe to set.
+  row.briefingMarkdown = renderRelayRowBriefing(row);
+  return { row, rowState };
+}
+
+// Fetch the verified task object for a row that points at a task. The real API
+// shape of GET /v1/tasks/:taskId (RelayClient.getTask) is `{ task: Task }` — a
+// wrapper object, never a bare Task — so we unwrap response.task. Returns the
+// unwrapped Task (or null on any failure / unexpected shape) so the open still
+// proceeds with whatever the row carries.
+async function fetchTask(taskId, { log = () => {} } = {}) {
+  if (!taskId) return null;
+  try {
+    const { RelayClient } = await import("./client.js");
+    const client = new RelayClient();
+    const response = await client.getTask(taskId);
+    const task = response && typeof response === "object" ? response.task : null;
+    return task && typeof task === "object" ? task : null;
+  } catch (error) {
+    log(`relay task fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+function resolveCwd() {
+  // The cloud companion has no per-row source cwd; open the host session in the
+  // user's home so it lands in a stable, writable working directory.
+  return process.env.RELAY_OPEN_CWD || os.homedir();
+}
+
+export async function openRelay({ id, host = "claude", log = () => {} } = {}) {
+  if (!id) throw new Error("openRelay requires a row id");
+  const cleanHost = String(host || "claude").toLowerCase();
+  const { row, rowState } = await resolveRow(id, { log });
+  return materializeRowInHost({ id, row, rowState, host: cleanHost, log });
+}
+
+// Materialize a resolved row into the foregrounded host (Codex thread or Claude
+// native session). Shared by openRelay (staged companion row) and openTask
+// (synthetic task-open row). Returns the CLI contract
+// { id, host, url, openedInHost, skipExternalOpen }.
+async function materializeRowInHost({ id, row, rowState = {}, host = "claude", log = () => {} }) {
+  const cleanHost = String(host || "claude").toLowerCase();
+  const cwd = resolveCwd();
+  // The human reads `visible`; the agent-only `operatorNote` (real ids + the tool
+  // call to make) rides a hidden channel per host (Claude: a system-meta transcript
+  // row; Codex: developerInstructions) so it never enters the visible transcript.
+  const { visible: briefing, operatorNote } = renderRelayRowSeed(row);
+  let url = null;
+  let openedInHost = false;
+  let skipExternalOpen = false;
+
+  if (cleanHost === "codex") {
+    let threadId = rowState.threadId || null;
+    let sessionPath = rowState.sessionPath || null;
+    if (!threadId || !codexRolloutExists(threadId)) {
+      const thread = await createCodexThread({ row, briefing, operatorNote, cwd });
+      threadId = thread.id;
+      sessionPath = thread.path;
+      rememberRow(id, {
+        threadId,
+        sessionPath,
+        title: row.displayTitle,
+        materializedSurfaces: {
+          codex: true,
+          claudeCode: Boolean(rowState.materializedSurfaces?.claudeCode || rowState.claudeNativeSession),
+          claudeCowork: Boolean(rowState.materializedSurfaces?.claudeCowork),
+        },
+        materializedAt: new Date().toISOString(),
+      });
+    }
+    ensureRelayCodexIndexMarker({ threadId, sessionPath, packetId: id });
+    finalizeCodexThreadState({
+      threadId,
+      title: row.displayTitle,
+      cwd,
+      preview: relayThreadPreview(row),
+    });
+    try {
+      setThreadPinned(threadId, true);
+    } catch {}
+    await waitForCodexOpenReadiness(threadId);
+    const desktopOpenResult = await refreshCodexDesktopForThreads([threadId], { force: true, openThreadId: threadId });
+    openedInHost = Boolean(desktopOpenResult?.ok);
+    skipExternalOpen = openedInHost;
+    url = `codex://threads/${encodeURIComponent(threadId)}`;
+  } else {
+    let claudeNativeSession = rowState.claudeNativeSession || null;
+    if (!isClaudeNativeSessionImported(claudeNativeSession)) {
+      const claude = materializeRowForClaude(row, { cwd, forceClaudeCode: true });
+      claudeNativeSession = claude.nativeSession || null;
+      const previousSurfaces = rowState.materializedSurfaces || {};
+      rememberRow(id, {
+        claudeMarkdownPaths: claude.paths,
+        claudeNativeSession,
+        materializedSurfaces: {
+          codex: Boolean(previousSurfaces.codex || rowState.threadId),
+          claudeCode: Boolean(previousSurfaces.claudeCode || claude.nativeSession || claude.surfaces?.claudeCode),
+          claudeCowork: Boolean(previousSurfaces.claudeCowork || claude.surfaces?.claudeCowork),
+        },
+        materializedAt: new Date().toISOString(),
+        title: row.displayTitle,
+      });
+    } else {
+      claudeNativeSession = ensureClaudeDesktopImported(claudeNativeSession, {
+        title: relayRowTitle(row),
+        cwd,
+        createdAt: row.createdAt,
+      });
+      rememberRow(id, { claudeNativeSession });
+    }
+    url = claudeNativeSession?.deepLink || claudeNativeSession?.desktopImport?.deepLink || null;
+  }
+
+  return { id, host: cleanHost, url, openedInHost, skipExternalOpen };
+}
+
+// `relay open --task <taskId> --host <host>` — materialize a Relay task into a
+// visible native agent session (exactly like a staged relay row). The task object
+// (GET /v1/tasks/:id, unwrapped) carries title/objective/state but NO messages or
+// results, so the seed instructs the materialized session to call
+// relay_task_status(taskId) for live detail. Works the same for active and
+// completed tasks. The synthetic row caches under packets[`task:<taskId>`] and
+// carries no `direction` field, so the overlay pill (which filters
+// direction==='inbound') never lists it.
+export async function openTask({ taskId, host = "claude", log = () => {} } = {}) {
+  if (!taskId) throw new Error("openTask requires a taskId");
+  const task = await fetchTask(taskId, { log });
+  const id = `task:${taskId}`;
+  const rowState = getRowState(id) || {};
+  const taskTitle = (task && task.title) || "Relay task";
+  const row = {
+    id,
+    taskId,
+    relayNotificationKind: "task_open",
+    senderName: "Relay task",
+    title: taskTitle,
+    displayTitle: `🔁 Task: ${task?.title || taskId}`,
+    task: task || null,
+    createdAt: task?.updatedAt || task?.createdAt || "",
+  };
+  row.briefingMarkdown = row.bodyMarkdown = renderTaskOpenBriefing(task, taskId);
+  return materializeRowInHost({ id, row, rowState, host, log });
+}
+
+async function waitForCodexOpenReadiness(threadId) {
+  const deadline = Date.now() + Number(process.env.RELAY_CODEX_ROW_TIMEOUT_MS || 6000);
+  while (!codexThreadRowExists(threadId) && Date.now() < deadline) {
+    await sleep(150);
+  }
+  const settleMs = Number(process.env.RELAY_CODEX_OPEN_SETTLE_MS || 250);
+  if (settleMs > 0) await sleep(settleMs);
+}
+
+function codexRolloutExists(threadId) {
+  if (!threadId) return false;
+  try {
+    const sessionPath = findCodexSessionPath(threadId);
+    return Boolean(sessionPath && fs.existsSync(sessionPath));
+  } catch {
+    return false;
+  }
+}
+
+async function createCodexThread({ row, briefing, operatorNote = "", cwd }) {
+  return withCodexAppServer(async (client) => {
+    // developerInstructions is Codex's hidden, non-rendered channel. The base
+    // framing plus the agent-only operatorNote (real ids + the tool call) live here
+    // so the human-visible transcript stays clean — only `briefing` (the visible
+    // body) is appended as the assistant turn below.
+    const developerInstructions = [
+      "This thread was materialized by Relay Companion. The first visible content is one Relay message authored by the sending agent. It may be a plain note, a question, or a context handoff; treat it according to its content unless the local user asks otherwise.",
+      String(operatorNote || "").trim(),
+    ]
+      .filter(Boolean)
+      .join("\n\n");
+    const started = await client.request("thread/start", {
+      cwd,
+      approvalPolicy: "never",
+      sandbox: "danger-full-access",
+      threadSource: "user",
+      developerInstructions,
+    });
+    const threadId = started.thread.id;
+    const sessionPath = started.thread.path || findCodexSessionPath(threadId);
+    await client.request("thread/name/set", { threadId, name: row.displayTitle });
+    appendVisibleAssistantTurn({ sessionPath, text: briefing, cwd });
+    const deadline = Date.now() + Number(process.env.RELAY_CODEX_ROW_TIMEOUT_MS || 6000);
+    while (!codexThreadRowExists(threadId) && Date.now() < deadline) {
+      await sleep(150);
+    }
+    finalizeCodexThreadState({
+      threadId,
+      title: row.displayTitle,
+      cwd,
+      preview: relayThreadPreview(row),
+    });
+    await client.request("thread/name/set", { threadId, name: row.displayTitle });
+    return { id: threadId, cwd, path: sessionPath, rowPersisted: codexThreadRowExists(threadId) };
+  });
+}
+
+function ensureRelayCodexIndexMarker({ threadId, sessionPath, packetId }) {
+  const resolvedSessionPath = sessionPath || findCodexSessionPath(threadId);
+  if (!resolvedSessionPath) return null;
+  try {
+    return ensureCodexThreadIndexMarker({ sessionPath: resolvedSessionPath, markerId: packetId || threadId });
+  } catch {
+    return null;
+  }
+}
+
+async function refreshCodexDesktopForThreads(threadIds, { force = false, openThreadId = null } = {}) {
+  const uniqueThreadIds = Array.from(new Set(threadIds.filter(Boolean)));
+  if (!uniqueThreadIds.length && !force) return null;
+  try {
+    const result = await notifyCodexDesktopThreads({
+      threadIds: uniqueThreadIds,
+      pinnedThreadIds: readPinnedThreadIds(),
+      openThreadId,
+    });
+    if (process.env.RELAY_DEBUG && result.attempted && !result.ok) {
+      console.error(`Relay Codex desktop refresh did not reach a running window: ${JSON.stringify(result)}`);
+    }
+    return result;
+  } catch (error) {
+    if (process.env.RELAY_DEBUG) {
+      console.error(`Relay Codex desktop refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return null;
+  }
+}
+
+// Exposed so a `relay repair claude` style command (or tests) can drive the
+// Claude Desktop title repair pass, mirroring the original.
+export function repairClaudeTitles() {
+  return repairClaudeDesktopRelaySessions();
+}
+
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    if (String(value || "").trim()) return value;
+  }
+  return "";
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}