relay-companion 0.1.0

package/src/notifications.js

@@ -0,0 +1,412 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { webUrl } from "./config.js";
+import { relayBinPath } from "./install.js";
+
+const DEFAULT_COMPANION_STATE = {
+  version: 1,
+  profile: {
+    name: "",
+    handle: "",
+    email: "",
+    inboxDir: "",
+    contactCardRoots: [],
+    transport: { type: "filesystem" },
+  },
+  contacts: [],
+  packets: {},
+  meetingNotes: {},
+  setup: {},
+  emailThreads: {},
+  chats: {},
+};
+
+function absoluteActionUrl(pathOrUrl) {
+  if (!pathOrUrl) return webUrl();
+  if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
+  const path = pathOrUrl.startsWith("/") ? pathOrUrl : `/${pathOrUrl}`;
+  return `${webUrl()}${path}`;
+}
+
+export function notificationActionUrl(notification) {
+  return notification.actionUrl || absoluteActionUrl(notification.url);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function relayCliCommand(args) {
+  return [process.execPath, relayBinPath(), ...args].map(shellQuote).join(" ");
+}
+
+function relayAnswerCommand(taskId, messageId) {
+  return relayCliCommand(["answer-question", "--task", taskId, "--message", messageId, "--answer", "..."]);
+}
+
+function actionForNotification(notification) {
+  if (notification.kind === "human_question") {
+    return {
+      type: "answer_question",
+      taskId: notification.taskId,
+      messageId: notification.messageId,
+      url: notificationActionUrl(notification),
+      command: relayAnswerCommand(notification.taskId, notification.messageId),
+    };
+  }
+  if (notification.kind === "task_request") {
+    return {
+      type: "task_request",
+      taskId: notification.taskId,
+      participantId: notification.participantId,
+      url: notificationActionUrl(notification),
+      actions: [
+        { id: "accept", label: "Accept", method: "accept_task_invitation" },
+        { id: "reject", label: "Reject", method: "reject_task_invitation" },
+      ],
+    };
+  }
+  if (notification.kind === "share_approval") {
+    return {
+      type: "review_share_approval",
+      taskId: notification.taskId,
+      url: notificationActionUrl(notification),
+      actions: [
+        { id: "send", label: "Send", method: "approve_share" },
+        { id: "decline", label: "Decline", method: "decline_share" },
+      ],
+    };
+  }
+  return {
+    type: "open",
+    url: notificationActionUrl(notification),
+  };
+}
+
+function participantForUser(task, user) {
+  return (task.participants || []).find((participant) => (
+    participant.userId === user?.id || participant.email === user?.email
+  ));
+}
+
+function taskNotification(task, kind, title, body, url, extra = {}) {
+  const base = {
+    id: `${kind}:${task.id}:${task.updatedAt || ""}`,
+    kind,
+    title,
+    body,
+    url,
+    taskId: task.id,
+    createdAt: task.updatedAt || task.createdAt || null,
+    ...extra,
+  };
+  return {
+    ...base,
+    action: actionForNotification(base),
+  };
+}
+
+export function buildHumanNotifications({ user, tasks = [], relays = [], connectors = [] } = {}) {
+  const notifications = [];
+  for (const task of tasks) {
+    const participant = participantForUser(task, user);
+    if (
+      task.viewerRole === "participant" &&
+      participant &&
+      ["created", "delivered"].includes(participant.invitationState) &&
+      task.state === "inviting"
+    ) {
+      notifications.push(taskNotification(
+        task,
+        "task_request",
+        "Relay task request",
+        `${task.title}: ${task.objective}`,
+        `/app/tasks/${task.id}`,
+        { participantId: participant.id },
+      ));
+    }
+    if (task.pendingApprovalCount > 0) {
+      notifications.push(taskNotification(
+        task,
+        "share_approval",
+        "Relay approval needed",
+        `${task.pendingApprovalCount} outbound share approval${task.pendingApprovalCount === 1 ? "" : "s"} waiting for ${task.title}.`,
+        `/app/tasks/${task.id}`,
+      ));
+    }
+    if (task.state === "completed") {
+      notifications.push(taskNotification(task, "task_completed", "Relay task completed", task.title, `/app/tasks/${task.id}`));
+    }
+    if (task.state === "cancelled" || task.state === "failed") {
+      notifications.push(taskNotification(task, `task_${task.state}`, `Relay task ${task.state}`, task.title, `/app/tasks/${task.id}`));
+    }
+  }
+
+  for (const relay of relays) {
+    if (!relay.requiresAnswer) continue;
+    const question = relay.message?.humanResponse?.question || relay.message?.bodyMarkdown || relay.task.title;
+    // A human_question is a relay_to_human message with humanResponse.mode=required_before_resume,
+    // which the contract defines as an agent asking its OWN human (mcp.js relay_to_human doc).
+    // Carry the message's real senderLabel (TaskMessage.senderLabel, protocol.ts) when present;
+    // otherwise it is the viewer's own agent, so "Your agent" — never the brand word "Relay".
+    const questionSender = String(relay.message?.senderLabel || "").trim() || "Your agent";
+    const notification = {
+      id: `human_question:${relay.message.id}:${relay.message.updatedAt || ""}`,
+      kind: "human_question",
+      title: "Relay question needs your answer",
+      body: question,
+      senderName: questionSender,
+      url: `/app/relays`,
+      taskId: relay.task.id,
+      messageId: relay.message.id,
+      quickReply: true,
+      createdAt: relay.message.updatedAt || relay.message.createdAt || null,
+    };
+    notifications.push({ ...notification, action: actionForNotification(notification) });
+  }
+
+  for (const connector of connectors) {
+    if (!["expired", "reconnect_required", "admin_consent_required", "error"].includes(connector.status)) continue;
+    const notification = {
+      id: `connector:${connector.provider}:${connector.status}:${connector.lastCheckedAt || ""}`,
+      kind: "connector_reauth",
+      title: `${connector.displayName} needs attention`,
+      body: connector.errorMessage || `${connector.displayName} is ${connector.status.replaceAll("_", " ")}.`,
+      url: "/app/connectors",
+      provider: connector.provider,
+      createdAt: connector.lastCheckedAt || null,
+    };
+    notifications.push({ ...notification, action: actionForNotification(notification) });
+  }
+  return notifications;
+}
+
+export function freshNotifications(ledger, notifications) {
+  const seen = ledger.notifications || {};
+  return notifications.filter((notification) => !seen[notification.id]);
+}
+
+export function markNotificationsProcessed(ledger, notifications) {
+  ledger.notifications ||= {};
+  const processedAt = new Date().toISOString();
+  for (const notification of notifications) {
+    ledger.notifications[notification.id] = {
+      kind: notification.kind,
+      processedAt,
+    };
+  }
+}
+
+export function companionHome() {
+  return process.env.RELAY_HOME || process.env.RELAY_COMPANION_HOME || path.join(os.homedir(), ".relay-companion");
+}
+
+export function companionStatePath(dir = companionHome()) {
+  return path.join(dir, "state.json");
+}
+
+function readCompanionState(statePath) {
+  try {
+    return {
+      ...structuredClone(DEFAULT_COMPANION_STATE),
+      ...JSON.parse(fs.readFileSync(statePath, "utf8")),
+    };
+  } catch {
+    return structuredClone(DEFAULT_COMPANION_STATE);
+  }
+}
+
+function writeCompanionState(statePath, state) {
+  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 notificationUrgency(kind) {
+  if (kind === "human_question") return "blocking";
+  if (kind === "task_request" || kind === "share_approval") return "action_required";
+  if (kind === "connector_reauth") return "attention";
+  if (kind === "task_failed" || kind === "task_cancelled") return "problem";
+  return "normal";
+}
+
+function senderForNotification(notification) {
+  // Always prefer the real sender carried on the notification (e.g. the question's
+  // TaskMessage.senderLabel or the other person's name). Never surface the brand word
+  // "Relay" as if it were a person.
+  if (notification.senderName) return notification.senderName;
+  // A human_question is the viewer's own agent asking them (relay_to_human +
+  // humanResponse.mode=required_before_resume per the relay_to_human contract).
+  if (notification.kind === "human_question") return "Your agent";
+  // task_request / share_approval are workflow notices, not people; label them as the
+  // automation, not as "Relay" the person. (These are filtered out of the Relays list
+  // anyway via RELAY_HIDDEN_KINDS, but the staged senderName must still be coherent.)
+  if (notification.kind === "task_request") return "Your agent";
+  if (notification.kind === "share_approval") return "Your agent";
+  if (notification.kind === "connector_reauth") return "Relay connectors";
+  return "Someone";
+}
+
+function subjectForNotification(notification) {
+  if (notification.kind === "human_question" && notification.body) return notification.body;
+  if (notification.kind === "task_request" && notification.body) return notification.body;
+  if (notification.kind === "share_approval" && notification.body) return notification.body;
+  return notification.title || notification.body || "Relay";
+}
+
+function notificationSender(notification) {
+  return {
+    name: senderForNotification(notification),
+    handle: "relay",
+    email: "",
+    host: "relay",
+  };
+}
+
+function notificationRecipient() {
+  return {
+    name: "You",
+    handle: "you",
+    email: "",
+    ai: "codex",
+  };
+}
+
+function packetMarkdownForNotification(notification) {
+  const lines = [
+    notification.body || notification.title || "Relay needs your attention.",
+    "",
+    "---",
+    `Relay attention item: ${notification.kind || "relay"}`,
+  ];
+  if (notification.taskId) lines.push(`Task id: \`${notification.taskId}\``);
+  if (notification.messageId) lines.push(`Message id: \`${notification.messageId}\``);
+  if (notification.participantId) lines.push(`Participant id: \`${notification.participantId}\``);
+  if (notification.provider) lines.push(`Connector: \`${notification.provider}\``);
+  if (notification.kind === "human_question") {
+    lines.push("");
+    lines.push(
+      "This is a blocking Relay task question. Discuss it with the human, then call `relay_answer_human_question` with the task id, message id, and the human's answer.",
+    );
+  } else if (notification.kind === "task_request") {
+    lines.push("");
+    lines.push("This is a Relay task request. The human must accept or reject before their agent participates.");
+  } else if (notification.kind === "share_approval") {
+    lines.push("");
+    lines.push("This is a Relay share approval. No cross-person information has been sent yet.");
+  }
+  return lines.join("\n");
+}
+
+function writeNotificationPacketContent(notification, packet, statePath) {
+  const dir = path.join(path.dirname(statePath), "packets");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const contentPath = path.join(dir, `${packet.id}.json`);
+  const tmp = `${contentPath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(packet, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, contentPath);
+  return contentPath;
+}
+
+function relayPacketFromNotification(notification, { now = new Date().toISOString() } = {}) {
+  const subject = subjectForNotification(notification);
+  const sender = notificationSender(notification);
+  return {
+    schemaVersion: 1,
+    id: notification.id,
+    createdAt: notification.createdAt || now,
+    updatedAt: now,
+    state: "unread",
+    sender,
+    recipient: notificationRecipient(),
+    source: {
+      host: "relay",
+      surface: "relay_companion",
+      threadId: null,
+      cwd: process.cwd(),
+    },
+    kind: "message",
+    title: subject,
+    displayTitle: subject,
+    userInstructions: "",
+    includeDefaultTranscript: false,
+    briefingMarkdown: packetMarkdownForNotification(notification),
+    attachments: [],
+    delivery: {
+      transport: "relay_task",
+      targetSurfaces: ["codex", "claude_code"],
+      recipientInboxDir: "",
+      outboxPath: null,
+      inboxPath: null,
+    },
+  };
+}
+
+export function relayCompanionRowFromNotification(
+  notification,
+  { now = new Date().toISOString(), contentPath = null } = {},
+) {
+  const actionUrl = notificationActionUrl(notification);
+  const subject = subjectForNotification(notification);
+  return {
+    id: notification.id,
+    direction: "inbound",
+    state: "unread",
+    kind: "message",
+    // Default unknown notification kinds to a neutral "message", never "task_completed"
+    // (which would falsely mark an unknown row as a finished task). main.cjs readRelays
+    // also defaults to "task_completed"; staging a real kind here keeps that fallback unused.
+    relayNotificationKind: notification.kind || "message",
+    urgency: notificationUrgency(notification.kind),
+    senderName: senderForNotification(notification),
+    title: subject,
+    displayTitle: subject,
+    briefingMarkdown: packetMarkdownForNotification(notification),
+    bodyMarkdown: notification.body || notification.title || "",
+    createdAt: notification.createdAt || now,
+    updatedAt: now,
+    stagedAt: now,
+    actionUrl,
+    action: notification.action || actionForNotification(notification),
+    quickReply: Boolean(notification.quickReply),
+    taskId: notification.taskId || null,
+    participantId: notification.participantId || null,
+    messageId: notification.messageId || null,
+    provider: notification.provider || null,
+    contentPath,
+    filePath: contentPath,
+    attachments: [],
+    materializationDeferredReason: "relay_pill",
+    materializedSurfaces: { codex: false, claudeCode: false, claudeCowork: false },
+  };
+}
+
+export function stageRelayCompanionItem(notification, { statePath = companionStatePath() } = {}) {
+  const state = readCompanionState(statePath);
+  state.packets ||= {};
+  state.chats ||= {};
+  const existing = state.packets[notification.id] || {};
+  const packet = relayPacketFromNotification(notification);
+  const contentPath = writeNotificationPacketContent(notification, packet, statePath);
+  const item = {
+    ...existing,
+    ...relayCompanionRowFromNotification(notification, { contentPath }),
+    state: existing.state === "read" ? "read" : "unread",
+  };
+  state.packets[item.id] = item;
+  writeCompanionState(statePath, state);
+  return {
+    ok: true,
+    transport: "relay_companion",
+    statePath,
+    itemId: item.id,
+    actionUrl: item.actionUrl,
+    contentPath,
+  };
+}
+
+export function defaultStageRelayCompanionItem(notification) {
+  return stageRelayCompanionItem(notification);
+}

package/src/pinning.js

@@ -0,0 +1,43 @@
+// Codex pinned-thread-ids writer. Ported faithfully from
+// granular/tools/relay-companion/src/pinning.js (paths -> host-paths.js,
+// writeJsonAtomic -> host-json.js). The open path pins the just-materialized
+// Relay thread so Codex Desktop surfaces it; readPinnedThreadIds feeds the
+// desktop refresh expression.
+
+import fs from "node:fs";
+import path from "node:path";
+import { codexGlobalStatePath } from "./host-paths.js";
+import { writeJsonAtomic } from "./host-json.js";
+
+export function readPinnedThreadIds() {
+  const filePath = codexGlobalStatePath();
+  if (!fs.existsSync(filePath)) return [];
+  const state = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  return Array.isArray(state["pinned-thread-ids"]) ? state["pinned-thread-ids"] : [];
+}
+
+export function writePinnedThreadIds(threadIds) {
+  if (!Array.isArray(threadIds)) throw new TypeError("threadIds must be an array");
+  const filePath = codexGlobalStatePath();
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const state = fs.existsSync(filePath) ? JSON.parse(fs.readFileSync(filePath, "utf8")) : {};
+  state["pinned-thread-ids"] = Array.from(new Set(threadIds.filter(Boolean)));
+  writeJsonAtomic(filePath, state);
+  return state["pinned-thread-ids"];
+}
+
+export function applyPinnedThreadPlan({ pinThreadIds = [], unpinThreadIds = [] }) {
+  const pinned = Array.from(new Set(pinThreadIds.filter(Boolean)));
+  const unpinned = new Set(unpinThreadIds.filter(Boolean));
+  const planned = new Set([...pinned, ...unpinned]);
+  const preserved = readPinnedThreadIds().filter((threadId) => !planned.has(threadId));
+  return writePinnedThreadIds([...pinned, ...preserved]);
+}
+
+export function setThreadPinned(threadId, pinned) {
+  if (!threadId) throw new Error("threadId is required");
+  return applyPinnedThreadPlan({
+    pinThreadIds: pinned ? [threadId] : [],
+    unpinThreadIds: pinned ? [] : [threadId],
+  });
+}