@erica-s/ai-agent-notify 2.1.5

package/lib/codex-sidecar-state.js

@@ -0,0 +1,314 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const SIDECAR_STATE_DIR = path.join(os.tmpdir(), "ai-agent-notify", "codex-mcp-sidecar");
+const STALE_UNRESOLVED_RECORD_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const STALE_RESOLVED_RECORD_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+function getSidecarStateDir() {
+  return SIDECAR_STATE_DIR;
+}
+
+function writeSidecarRecord(record) {
+  const normalized = normalizeRecord(record);
+  fs.mkdirSync(SIDECAR_STATE_DIR, { recursive: true });
+
+  const recordPath = getSidecarRecordPath(normalized.recordId);
+  const tempPath = `${recordPath}.tmp-${process.pid}`;
+
+  fs.writeFileSync(tempPath, JSON.stringify(normalized, null, 2), "utf8");
+  fs.renameSync(tempPath, recordPath);
+
+  return normalized;
+}
+
+function deleteSidecarRecord(recordId) {
+  const recordPath = getSidecarRecordPath(recordId);
+  if (!fs.existsSync(recordPath)) {
+    return;
+  }
+
+  try {
+    fs.unlinkSync(recordPath);
+  } catch {}
+}
+
+function readAllSidecarRecords(log) {
+  if (!fs.existsSync(SIDECAR_STATE_DIR)) {
+    return [];
+  }
+
+  let entries = [];
+  try {
+    entries = fs.readdirSync(SIDECAR_STATE_DIR, { withFileTypes: true });
+  } catch (error) {
+    if (typeof log === "function") {
+      log(`sidecar state readdir failed dir=${SIDECAR_STATE_DIR} error=${error.message}`);
+    }
+    return [];
+  }
+
+  const records = [];
+  entries.forEach((entry) => {
+    if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".json")) {
+      return;
+    }
+
+    const recordPath = path.join(SIDECAR_STATE_DIR, entry.name);
+    try {
+      const raw = fs.readFileSync(recordPath, "utf8");
+      records.push(normalizeRecord(JSON.parse(raw)));
+    } catch (error) {
+      if (typeof log === "function") {
+        log(`sidecar state parse failed file=${recordPath} error=${error.message}`);
+      }
+    }
+  });
+
+  return records;
+}
+
+function pruneStaleSidecarRecords(log) {
+  const now = Date.now();
+  readAllSidecarRecords(log).forEach((record) => {
+    const referenceTimeMs = parseTime(
+      record.lastMatchedAt || record.updatedAt || record.resolvedAt || record.startedAt
+    );
+    const maxAgeMs = record.sessionId
+      ? STALE_RESOLVED_RECORD_MAX_AGE_MS
+      : STALE_UNRESOLVED_RECORD_MAX_AGE_MS;
+    const isTooOld = !referenceTimeMs || now - referenceTimeMs > maxAgeMs;
+    if (isTooOld) {
+      deleteSidecarRecord(record.recordId);
+    }
+  });
+}
+
+function findSidecarTerminalContextForSession(sessionId, log) {
+  if (!sessionId) {
+    return null;
+  }
+
+  pruneStaleSidecarRecords(log);
+
+  const matches = readAllSidecarRecords(log)
+    .filter((record) => record.sessionId === sessionId)
+    .sort(compareRecordsByFreshness);
+
+  if (matches.length === 0) {
+    return null;
+  }
+
+  const match = writeSidecarRecord({
+    ...matches[0],
+    lastMatchedAt: new Date().toISOString(),
+  });
+  return {
+    recordId: match.recordId,
+    cwd: match.cwd || "",
+    hwnd: parsePositiveInteger(match.hwnd),
+    shellPid: parsePositiveInteger(match.shellPid),
+    isWindowsTerminal: match.isWindowsTerminal === true,
+    sessionId: match.sessionId,
+  };
+}
+
+function findSidecarTerminalContextForProjectDir(projectDir, log) {
+  if (!projectDir) {
+    return null;
+  }
+
+  pruneStaleSidecarRecords(log);
+
+  const matches = readAllSidecarRecords(log)
+    .map((record) => ({
+      record,
+      match: describeProjectDirMatch(record.cwd, projectDir),
+    }))
+    .filter(
+      (entry) =>
+        entry.match &&
+        !entry.record.sessionId &&
+        parsePositiveInteger(entry.record.hwnd) &&
+        isProcessAlive(entry.record.pid)
+    )
+    .sort(compareProjectDirFallbackCandidates);
+
+  if (matches.length === 0) {
+    return null;
+  }
+
+  const best = matches[0];
+  const second = matches[1];
+  if (
+    second &&
+    best.match.relationPriority === second.match.relationPriority &&
+    best.match.distance === second.match.distance &&
+    best.match.commonSegments === second.match.commonSegments
+  ) {
+    return null;
+  }
+
+  if (typeof log === "function") {
+    log(
+      `sidecar cwd fallback matched projectDir=${projectDir} recordCwd=${best.record.cwd || ""} hwnd=${best.record.hwnd || ""} pid=${best.record.pid || ""}`
+    );
+  }
+
+  return {
+    recordId: best.record.recordId,
+    cwd: best.record.cwd || "",
+    hwnd: parsePositiveInteger(best.record.hwnd),
+    shellPid: null,
+    isWindowsTerminal: false,
+    sessionId: "",
+  };
+}
+
+function getSidecarRecordPath(recordId) {
+  const safeId = String(recordId || "unknown").replace(/[^A-Za-z0-9._-]/g, "_");
+  return path.join(SIDECAR_STATE_DIR, `${safeId}.json`);
+}
+
+function normalizeRecord(record) {
+  const now = new Date().toISOString();
+  const normalized = record && typeof record === "object" ? { ...record } : {};
+
+  normalized.recordId = String(normalized.recordId || `${process.pid}`);
+  normalized.kind = "codex-mcp-sidecar";
+  normalized.pid = parsePositiveInteger(normalized.pid);
+  normalized.parentPid = parsePositiveInteger(normalized.parentPid);
+  normalized.hwnd = parsePositiveInteger(normalized.hwnd);
+  normalized.shellPid = parsePositiveInteger(normalized.shellPid);
+  normalized.isWindowsTerminal = normalized.isWindowsTerminal === true;
+  normalized.cwd = typeof normalized.cwd === "string" ? normalized.cwd : "";
+  normalized.sessionId = typeof normalized.sessionId === "string" ? normalized.sessionId : "";
+  normalized.startedAt = typeof normalized.startedAt === "string" ? normalized.startedAt : now;
+  normalized.updatedAt = now;
+  normalized.resolvedAt =
+    typeof normalized.resolvedAt === "string" ? normalized.resolvedAt : "";
+  normalized.lastMatchedAt =
+    typeof normalized.lastMatchedAt === "string" ? normalized.lastMatchedAt : "";
+
+  return normalized;
+}
+
+function compareRecordsByFreshness(left, right) {
+  return (
+    parseTime(right.resolvedAt) - parseTime(left.resolvedAt) ||
+    parseTime(right.updatedAt) - parseTime(left.updatedAt) ||
+    parseTime(right.startedAt) - parseTime(left.startedAt)
+  );
+}
+
+function parsePositiveInteger(value) {
+  const parsed = parseInt(value, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function parseTime(value) {
+  const parsed = Date.parse(value || "");
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function isProcessAlive(pid) {
+  const normalizedPid = parsePositiveInteger(pid);
+  if (!normalizedPid) {
+    return false;
+  }
+
+  try {
+    process.kill(normalizedPid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === "EPERM";
+  }
+}
+
+function describeProjectDirMatch(recordCwd, projectDir) {
+  const normalizedRecord = normalizeWindowsPath(recordCwd);
+  const normalizedProject = normalizeWindowsPath(projectDir);
+  if (!normalizedRecord || !normalizedProject) {
+    return null;
+  }
+
+  const recordSegments = splitWindowsPath(normalizedRecord);
+  const projectSegments = splitWindowsPath(normalizedProject);
+  const commonSegments = countCommonSegments(recordSegments, projectSegments);
+
+  if (normalizedRecord === normalizedProject) {
+    return {
+      relation: "exact",
+      relationPriority: 3,
+      distance: 0,
+      commonSegments,
+    };
+  }
+
+  if (normalizedRecord.startsWith(`${normalizedProject}\\`)) {
+    return {
+      relation: "record_inside_project",
+      relationPriority: 2,
+      distance: Math.max(0, recordSegments.length - projectSegments.length),
+      commonSegments,
+    };
+  }
+
+  if (normalizedProject.startsWith(`${normalizedRecord}\\`)) {
+    return {
+      relation: "project_inside_record",
+      relationPriority: 1,
+      distance: Math.max(0, projectSegments.length - recordSegments.length),
+      commonSegments,
+    };
+  }
+
+  return null;
+}
+
+function compareProjectDirFallbackCandidates(left, right) {
+  return (
+    right.match.relationPriority - left.match.relationPriority ||
+    left.match.distance - right.match.distance ||
+    right.match.commonSegments - left.match.commonSegments ||
+    parseTime(right.record.updatedAt) - parseTime(left.record.updatedAt) ||
+    parseTime(right.record.startedAt) - parseTime(left.record.startedAt)
+  );
+}
+
+function normalizeWindowsPath(value) {
+  try {
+    return path.resolve(value || "").replace(/\//g, "\\").toLowerCase();
+  } catch {
+    return String(value || "")
+      .replace(/\//g, "\\")
+      .toLowerCase();
+  }
+}
+
+function splitWindowsPath(value) {
+  return String(value || "")
+    .split("\\")
+    .filter(Boolean);
+}
+
+function countCommonSegments(left, right) {
+  const max = Math.min(left.length, right.length);
+  let count = 0;
+
+  while (count < max && left[count] === right[count]) {
+    count += 1;
+  }
+
+  return count;
+}
+
+module.exports = {
+  deleteSidecarRecord,
+  findSidecarTerminalContextForProjectDir,
+  findSidecarTerminalContextForSession,
+  getSidecarStateDir,
+  pruneStaleSidecarRecords,
+  writeSidecarRecord,
+};

package/lib/notification-sources.js

@@ -0,0 +1,411 @@
+"use strict";
+
+const CODEX_EVENT_NAME_BY_TYPE = {
+  "agent-turn-complete": "Stop",
+  "approval-requested": "PermissionRequest",
+  "exec-approval-request": "PermissionRequest",
+  "request-permissions": "PermissionRequest",
+  "apply-patch-approval-request": "PermissionRequest",
+};
+const ENV_PAYLOAD_KEYS = ["AI_AGENT_NOTIFY_PAYLOAD"];
+
+function normalizeIncomingNotification({ argv = [], stdinData = "", env = {} } = {}) {
+  const candidates = getIncomingPayloadCandidates(argv, stdinData, env);
+  const explicitOverrides = getExplicitDisplayOverrides(env);
+
+  for (const candidate of candidates) {
+    const normalized =
+      normalizeClaudeHookPayload(candidate) ||
+      normalizeCodexLegacyNotifyPayload(candidate) ||
+      normalizeGenericJsonPayload(candidate);
+
+    if (normalized) {
+      return applyExplicitDisplayOverrides(normalized, explicitOverrides);
+    }
+  }
+
+  return applyExplicitDisplayOverrides(
+    createNotificationSpec({
+      sourceId: "unknown",
+      transport: candidates.length > 0 ? candidates[0].transport : "none",
+      sessionId: "unknown",
+      payloadKeys: [],
+      debugSummary:
+        candidates.length > 0 ? buildCandidateSummary(candidates[0]) : "payload transport=none",
+    }),
+    explicitOverrides
+  );
+}
+
+function getIncomingPayloadCandidates(argv, stdinData, env) {
+  const candidates = [];
+
+  pushPayloadCandidate(candidates, {
+    transport: "stdin",
+    raw: stdinData,
+    acceptNonJson: true,
+  });
+
+  for (const envKey of ENV_PAYLOAD_KEYS) {
+    pushPayloadCandidate(candidates, {
+      transport: `env:${envKey}`,
+      raw: env && typeof env === "object" ? env[envKey] : "",
+      acceptNonJson: false,
+    });
+  }
+
+  for (let index = argv.length - 1; index >= 0; index -= 1) {
+    pushPayloadCandidate(candidates, {
+      transport: `argv[${index}]`,
+      raw: argv[index],
+      acceptNonJson: false,
+    });
+  }
+
+  return dedupePayloadCandidates(candidates);
+}
+
+function pushPayloadCandidate(candidates, { transport, raw, acceptNonJson }) {
+  const trimmed = normalizePayloadString(raw);
+  if (!trimmed) {
+    return;
+  }
+
+  if (!acceptNonJson && !looksLikeJson(trimmed)) {
+    return;
+  }
+
+  const parsed = parseJsonMaybe(trimmed);
+  candidates.push({
+    transport,
+    raw: trimmed,
+    parsed,
+    parseState: describeParsedValue(parsed),
+  });
+}
+
+function dedupePayloadCandidates(candidates) {
+  const seen = new Set();
+  return candidates.filter((candidate) => {
+    const key = `${candidate.transport}:${candidate.raw}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}
+
+function normalizeClaudeHookPayload(candidate) {
+  const payload = candidate.parsed;
+  if (!isPlainObject(payload)) {
+    return null;
+  }
+
+  if (!hasAnyKey(payload, ["hook_event_name", "session_id", "title", "message", "source"])) {
+    return null;
+  }
+
+  return createNotificationSpec({
+    sourceId: "claude-hook",
+    source: getStringField(payload, ["source"]),
+    transport: candidate.transport,
+    sessionId: getStringField(payload, ["session_id"]) || "unknown",
+    eventName: getStringField(payload, ["hook_event_name"]),
+    title: getStringField(payload, ["title"]),
+    message: getStringField(payload, ["message"]),
+    rawEventType: getStringField(payload, ["hook_event_name"]),
+    payloadKeys: Object.keys(payload).sort(),
+    debugSummary: buildCandidateSummary(candidate),
+  });
+}
+
+function normalizeCodexLegacyNotifyPayload(candidate) {
+  const payload = candidate.parsed;
+  if (!isPlainObject(payload)) {
+    return null;
+  }
+
+  const rawEventType = getStringField(payload, ["type"]);
+  const sessionId =
+    getStringField(payload, ["thread-id", "thread_id", "threadId"]) ||
+    getStringField(payload, ["turn-id", "turn_id", "turnId"]) ||
+    "unknown";
+  const turnId = getStringField(payload, ["turn-id", "turn_id", "turnId"]);
+  const client = getStringField(payload, ["client"]);
+  const projectDir = getStringField(payload, ["cwd", "project-dir", "project_dir", "projectDir"]);
+  const hasCodexShape =
+    !!rawEventType &&
+    (client.startsWith("codex") ||
+      hasAnyKey(payload, [
+        "thread-id",
+        "thread_id",
+        "threadId",
+        "turn-id",
+        "turn_id",
+        "turnId",
+        "cwd",
+        "input-messages",
+        "input_messages",
+        "last-assistant-message",
+        "last_assistant_message",
+      ]));
+
+  if (!hasCodexShape) {
+    return null;
+  }
+
+  return createNotificationSpec({
+    sourceId: "codex-legacy-notify",
+    source: getStringField(payload, ["source"]),
+    transport: candidate.transport,
+    sessionId,
+    turnId,
+    eventName: CODEX_EVENT_NAME_BY_TYPE[rawEventType] || "",
+    title: getStringField(payload, ["title"]),
+    message: getStringField(payload, ["message"]),
+    projectDir,
+    rawEventType,
+    client,
+    payloadKeys: Object.keys(payload).sort(),
+    debugSummary: buildCandidateSummary(candidate),
+  });
+}
+
+function normalizeGenericJsonPayload(candidate) {
+  const payload = candidate.parsed;
+  if (!isPlainObject(payload)) {
+    return null;
+  }
+
+  return createNotificationSpec({
+    sourceId: inferSourceId(payload),
+    source: getStringField(payload, ["source"]),
+    transport: candidate.transport,
+    sessionId:
+      getStringField(payload, ["session_id", "thread-id", "thread_id", "threadId"]) || "unknown",
+    eventName: getStringField(payload, ["hook_event_name", "event", "type"]),
+    title: getStringField(payload, ["title"]),
+    message: getStringField(payload, ["message"]),
+    projectDir: getStringField(payload, ["cwd", "project-dir", "project_dir", "projectDir"]),
+    rawEventType: getStringField(payload, ["type"]),
+    client: getStringField(payload, ["client"]),
+    payloadKeys: Object.keys(payload).sort(),
+    debugSummary: buildCandidateSummary(candidate),
+  });
+}
+
+function inferSourceId(payload) {
+  const client = getStringField(payload, ["client"]);
+  if (client.startsWith("codex")) {
+    return "codex-json";
+  }
+
+  if (
+    hasAnyKey(payload, [
+      "thread-id",
+      "thread_id",
+      "threadId",
+      "turn-id",
+      "turn_id",
+      "turnId",
+      "input-messages",
+      "input_messages",
+      "last-assistant-message",
+      "last_assistant_message",
+    ])
+  ) {
+    return "codex-json";
+  }
+
+  if (hasAnyKey(payload, ["hook_event_name", "session_id"])) {
+    return "claude-hook";
+  }
+
+  return "unknown";
+}
+
+function createNotificationSpec(spec) {
+  const sourceId = spec.sourceId || spec.source || "unknown";
+  const eventName = spec.eventName || "";
+
+  return {
+    sourceId,
+    sourceFamily: getSourceFamily(sourceId),
+    source: canonicalizeDisplaySource(spec.source || inferDisplaySource(sourceId)),
+    transport: spec.transport || "",
+    sessionId: spec.sessionId || "unknown",
+    turnId: spec.turnId || "",
+    eventName,
+    title: canonicalizeNotificationTitle(spec.title || inferNotificationTitle(eventName)),
+    message: canonicalizeNotificationMessage(spec.message || inferNotificationMessage(eventName)),
+    projectDir: spec.projectDir || "",
+    rawEventType: spec.rawEventType || "",
+    payloadKeys: Array.isArray(spec.payloadKeys) ? spec.payloadKeys : [],
+    client: spec.client || "",
+    debugSummary: spec.debugSummary || "",
+  };
+}
+
+function applyExplicitDisplayOverrides(spec, overrides) {
+  return {
+    ...spec,
+    source: canonicalizeDisplaySource(overrides.source || spec.source),
+    title: canonicalizeNotificationTitle(overrides.title || spec.title),
+    message: canonicalizeNotificationMessage(overrides.message || spec.message),
+  };
+}
+
+function getExplicitDisplayOverrides(env) {
+  return {
+    source: getStringField(env, ["TOAST_NOTIFY_SOURCE"]),
+    title: getStringField(env, ["TOAST_NOTIFY_TITLE"]),
+    message: getStringField(env, ["TOAST_NOTIFY_MESSAGE"]),
+  };
+}
+
+function inferDisplaySource(sourceId) {
+  if (typeof sourceId === "string" && sourceId.startsWith("codex")) {
+    return "Codex";
+  }
+
+  if (typeof sourceId === "string" && sourceId.startsWith("claude")) {
+    return "Claude";
+  }
+
+  return "";
+}
+
+function inferNotificationTitle(eventName) {
+  switch (eventName) {
+    case "Stop":
+      return "Done";
+    case "PermissionRequest":
+      return "Needs Approval";
+    default:
+      return "Notification";
+  }
+}
+
+function inferNotificationMessage(eventName) {
+  switch (eventName) {
+    case "Stop":
+      return "Task finished";
+    case "PermissionRequest":
+      return "Waiting for your approval";
+    default:
+      return "Notification";
+  }
+}
+
+function canonicalizeDisplaySource(source) {
+  const trimmed = typeof source === "string" ? source.trim() : "";
+  if (!trimmed) {
+    return "";
+  }
+
+  if (/^claude(?:-hook)?$/i.test(trimmed)) {
+    return "Claude";
+  }
+
+  if (/^codex(?:[- ].+)?$/i.test(trimmed)) {
+    return "Codex";
+  }
+
+  if (/^(unknown|notification)$/i.test(trimmed)) {
+    return "";
+  }
+
+  return trimmed;
+}
+
+function canonicalizeNotificationTitle(title) {
+  const trimmed = typeof title === "string" ? title.trim() : "";
+  if (!trimmed) {
+    return "Notification";
+  }
+
+  return trimmed
+    .replace(/^\[(Claude|Codex|Agent)\]\s*/i, "")
+    .replace(/Needs Permission/g, "Needs Approval")
+    .replace(/^(Claude|Codex|Agent)\s+Needs Approval$/i, "Needs Approval")
+    .replace(/^(Claude|Codex|Agent)\s+Done$/i, "Done")
+    .replace(/^(Claude|Codex|Agent)$/i, "Notification");
+}
+
+function canonicalizeNotificationMessage(message) {
+  const trimmed = typeof message === "string" ? message.trim() : "";
+  return trimmed || "Notification";
+}
+
+function getSourceFamily(sourceId) {
+  if (typeof sourceId === "string" && sourceId.startsWith("codex")) {
+    return "codex";
+  }
+
+  if (typeof sourceId === "string" && sourceId.startsWith("claude")) {
+    return "claude";
+  }
+
+  return "generic";
+}
+
+function buildCandidateSummary(candidate) {
+  const keys = isPlainObject(candidate.parsed) ? Object.keys(candidate.parsed).sort().join(",") : "";
+  return `payload transport=${candidate.transport} parsed=${candidate.parseState} keys=${keys} rawLength=${candidate.raw.length}`;
+}
+
+function normalizePayloadString(value) {
+  return typeof value === "string" ? value.replace(/^\uFEFF/, "").trim() : "";
+}
+
+function parseJsonMaybe(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function looksLikeJson(value) {
+  return value.startsWith("{") || value.startsWith("[");
+}
+
+function describeParsedValue(value) {
+  if (Array.isArray(value)) {
+    return "array";
+  }
+
+  if (value && typeof value === "object") {
+    return "object";
+  }
+
+  return value === null ? "invalid" : typeof value;
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasAnyKey(payload, keys) {
+  return keys.some((key) => Object.prototype.hasOwnProperty.call(payload, key));
+}
+
+function getStringField(payload, keys) {
+  for (const key of keys) {
+    const value = payload[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+
+  return "";
+}
+
+module.exports = {
+  createNotificationSpec,
+  getIncomingPayloadCandidates,
+  getSourceFamily,
+  normalizeIncomingNotification,
+  parseJsonMaybe,
+};