@murmurv2/cli 2.11.0

package/runtime/scripts/murmur-shell-send.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// Standalone Murmur V2 sender for shell scripts and send-boundary services.
+// Reads agent-config.json from DATA_DIR, encrypts/signs/enqueues an envelope.
+
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { SQLiteDedupeOutboxStore, SQLiteMessageStore, stableEnvelopePayload, resolveMessageSubject } from "@murmurv2/core";
+import { encryptPayload, signEnvelope } from "@murmurv2/security";
+import { readPrivateJson } from "./secure-state.mjs";
+
+const args = process.argv.slice(2);
+const opt = {};
+for (let i = 0; i < args.length; i += 1) {
+  const a = args[i];
+  if (a === "--to") opt.to = args[++i];
+  else if (a === "--conv" || a === "--conversation") opt.conversationId = args[++i];
+  else if (a === "--channel") opt.channelId = args[++i];
+  else if (a === "--sender-member") opt.senderMemberId = args[++i];
+  else if (a === "--addressee-member") opt.addresseeMemberId = args[++i];
+  else if (a === "--text") opt.text = args[++i];
+  else if (a === "--text-file") opt.textFile = args[++i];
+  else if (a === "--stdin") opt.stdin = true;
+  else if (a === "--msg-id") opt.msgId = args[++i];
+  else if (a === "--help" || a === "-h") opt.help = true;
+}
+
+if (opt.help || !opt.to || (!opt.text && !opt.textFile && !opt.stdin)) {
+  process.stderr.write(
+    "usage: murmur-shell-send.mjs --to <peer-id> (--text <txt> | --text-file <path> | --stdin) [--conv <id>] [--msg-id <uuid>] [--channel <id> --sender-member <id> [--addressee-member <id>]]\n",
+  );
+  process.exit(1);
+}
+
+// `--msg-id` makes a send idempotent (#105): the caller supplies the id — the Codex wake
+// relay derives it from the inbound msgId — and a repeat with the same id changes nothing.
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+if (opt.msgId !== undefined && !UUID_RE.test(String(opt.msgId))) {
+  process.stderr.write("error: --msg-id must be a UUID\n");
+  process.exit(1);
+}
+
+if (opt.textFile) {
+  opt.text = readFileSync(opt.textFile, "utf8");
+} else if (opt.stdin) {
+  opt.text = readFileSync(0, "utf8");
+}
+const text = String(opt.text ?? "").trim();
+if (!text) {
+  process.stderr.write("error: text is empty\n");
+  process.exit(1);
+}
+
+const dataDir = process.env.DATA_DIR || ".data";
+const configPath = path.join(dataDir, "agent-config.json");
+const dbPath = process.env.MURMUR_STORE_PATH ?? path.join(dataDir, "murmur.db");
+
+let cfg;
+try {
+  cfg = await readPrivateJson(configPath);
+} catch (err) {
+  process.stderr.write(`error: cannot read ${configPath}: ${err.message}\n`);
+  process.exit(2);
+}
+
+const peer = cfg.peers?.[opt.to];
+if (!peer) {
+  process.stderr.write(`error: unknown peer '${opt.to}' in ${configPath}\n`);
+  process.exit(2);
+}
+
+const conversationId = opt.conversationId || `dm:${cfg.agentId}:${opt.to}`;
+const msgId = opt.msgId ? String(opt.msgId).toLowerCase() : randomUUID();
+const createdAt = new Date().toISOString();
+const optionalString = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
+const channelId = optionalString(opt.channelId) ?? optionalString(peer.channelId);
+const senderMemberId = optionalString(opt.senderMemberId) ?? optionalString(cfg.memberId);
+const addresseeMemberId = optionalString(opt.addresseeMemberId) ?? optionalString(peer.memberId);
+if ((channelId || senderMemberId || addresseeMemberId) && (!channelId || !senderMemberId)) {
+  process.stderr.write("error: channelId and senderMemberId are required together for structured routing\n");
+  process.exit(2);
+}
+const routing = channelId ? {
+  channelId,
+  senderMemberId,
+  ...(addresseeMemberId ? { addresseeMemberId } : {}),
+} : {};
+
+
+try {
+  const encrypted = await encryptPayload(
+    text,
+    peer.encryption.publicKey,
+    cfg.keys.encryption.privateKey,
+  );
+
+  const envelope = {
+    schemaVersion: "1.0",
+    msgId,
+    conversationId,
+    senderAgentId: cfg.agentId,
+    recipients: [opt.to],
+    createdAt,
+    payloadCiphertext: encrypted.ciphertext,
+    payloadNonce: encrypted.nonce,
+    signature: "",
+    ...routing,
+  };
+  envelope.signature = await signEnvelope(
+    stableEnvelopePayload(envelope),
+    cfg.keys.signing.privateKey,
+  );
+
+  const outbox = new SQLiteDedupeOutboxStore(dbPath);
+  outbox.db?.exec?.("PRAGMA busy_timeout=5000;");
+  if (opt.msgId && (await outbox.getOutboxRecord(msgId))) {
+    process.stdout.write(`${JSON.stringify({ msgId, to: opt.to, conversationId, status: "already-queued", ...routing })}\n`);
+    process.exit(0);
+  }
+  await outbox.enqueue(resolveMessageSubject(peer, channelId), envelope);
+
+  const store = new SQLiteMessageStore(dbPath);
+  store.db?.exec?.("PRAGMA busy_timeout=5000;");
+  await store.append({
+    conversationId,
+    msgId,
+    direction: "outbound",
+    sender: cfg.agentId,
+    text,
+    createdAt,
+    transport: "nats",
+    ...routing,
+  });
+
+  process.stdout.write(
+    `${JSON.stringify({ msgId, to: opt.to, conversationId, status: "queued", ...routing })}\n`,
+  );
+  process.exit(0);
+} catch (err) {
+  process.stderr.write(`error: enqueue failed: ${err.message}\n`);
+  process.exit(3);
+}

package/runtime/scripts/notify-router.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+import { DatabaseSync } from "node:sqlite";
+
+const nowIso = () => new Date().toISOString();
+
+const ensureArray = (value) => (Array.isArray(value) ? value : value ? [value] : []);
+
+// Optional sender filter on a notify target: `peers: ["agent-jarvis"]`.
+// A target without it stays a catch-all, so existing configs keep receiving
+// everything. Agent ids are compared case-insensitively.
+const normalizePeers = (value) => {
+  if (value === undefined) return undefined;
+  const list = ensureArray(value)
+    .filter((peer) => typeof peer === "string")
+    .map((peer) => peer.trim().toLowerCase())
+    .filter(Boolean);
+  return list;
+};
+
+const normalizeTelegram = (value, channelName = "telegram") => {
+  const list = ensureArray(value).filter(Boolean);
+  return list
+    .map((entry, i) => ({
+      type: "telegram",
+      channel: entry?.channel || `${channelName}${list.length > 1 ? `-${i + 1}` : ""}`,
+      botToken: entry?.botToken,
+      chatId: entry?.chatId,
+      topicId: entry?.topicId,
+      peers: normalizePeers(entry?.peers),
+      fallback: entry?.fallback === true || undefined,
+    }))
+    .filter((entry) => entry.botToken && entry.chatId);
+};
+
+const normalizeWebhook = (value, channelName = "webhook") => {
+  const list = ensureArray(value).filter(Boolean);
+  return list
+    .map((entry, i) => ({
+      type: "webhook",
+      channel: entry?.channel || entry?.name || `${channelName}${list.length > 1 ? `-${i + 1}` : ""}`,
+      url: entry?.url,
+      headers: entry?.headers && typeof entry.headers === "object" ? entry.headers : {},
+      peers: normalizePeers(entry?.peers),
+      fallback: entry?.fallback === true || undefined,
+    }))
+    .filter((entry) => entry.url);
+};
+
+export const normalizeNotifyTargets = (notifyConfig) => {
+  if (!notifyConfig) return [];
+
+  if (Array.isArray(notifyConfig)) {
+    return notifyConfig.flatMap((entry) => {
+      if (!entry || typeof entry !== "object") return [];
+      if (entry.type === "telegram") return normalizeTelegram(entry, entry.channel || "telegram");
+      if (entry.type === "webhook") return normalizeWebhook(entry, entry.channel || "webhook");
+      return [];
+    });
+  }
+
+  const targets = [];
+
+  if (notifyConfig.telegram) targets.push(...normalizeTelegram(notifyConfig.telegram, "telegram"));
+  if (notifyConfig.webhook) targets.push(...normalizeWebhook(notifyConfig.webhook, "webhook"));
+
+  // Backward compatibility: notify: { botToken, chatId, topicId }
+  if (!notifyConfig.telegram && notifyConfig.botToken && notifyConfig.chatId) {
+    targets.push(...normalizeTelegram(notifyConfig, "telegram"));
+  }
+
+  // Backward compatibility: notify: { url, headers }
+  if (!notifyConfig.webhook && notifyConfig.url) {
+    targets.push(...normalizeWebhook(notifyConfig, "webhook"));
+  }
+
+  return targets;
+};
+
+// Which targets a message from `sender` belongs to.
+//
+// Three kinds of target, and the difference matters when one chat has a thread
+// per peer:
+//   - `peers: [...]`      takes only those senders;
+//   - `fallback: true`    takes what no peer-filtered target took — a home for
+//                         a peer nobody made a thread for, without copying
+//                         every message into it;
+//   - neither             takes everything, which is what every config written
+//                         before this option did.
+export const targetsForSender = (targets, sender) => {
+  const from = String(sender || "").trim().toLowerCase();
+  const matched = targets.filter((target) => target.peers && from && target.peers.includes(from));
+  const always = targets.filter((target) => !target.peers && !target.fallback);
+  if (matched.length > 0) return [...matched, ...always];
+  return [...always, ...targets.filter((target) => target.fallback && !target.peers)];
+};
+
+// Both normal delivery and failed-wake notifications use this path, so routing
+// and the diagnostic for an unmatched peer cannot diverge between them.
+export const enqueuePeerNotification = ({ queue, targets, payload, log, reason }) => {
+  if (targets.length === 0 || payload.wakeEligible === false) return 0;
+  const selected = targetsForSender(targets, payload.from);
+  if (selected.length === 0) {
+    log("warn", "No notify target accepts this sender", {
+      msgId: payload.msgId, from: payload.from, targetCount: targets.length,
+      ...(reason ? { reason } : {}),
+    });
+    return 0;
+  }
+  queue.enqueueMessage(reason ? { ...payload, text: `[WakeMonitor ${reason}] ${payload.text}` } : payload, selected);
+  log("info", "Notifications queued", {
+    msgId: payload.msgId, targetCount: selected.length,
+    channels: selected.map((target) => target.channel).join(","),
+    ...(reason ? { reason } : {}),
+  });
+  return selected.length;
+};
+
+export class NotifyQueue {
+  constructor(dbPath) {
+    this.db = new DatabaseSync(dbPath);
+    this.db.exec(`
+      PRAGMA journal_mode=WAL;
+      PRAGMA busy_timeout=5000;
+      CREATE TABLE IF NOT EXISTS notify_queue (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        dedupe_key TEXT NOT NULL UNIQUE,
+        msg_id TEXT NOT NULL,
+        channel_type TEXT NOT NULL,
+        channel_name TEXT NOT NULL,
+        target_json TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        status TEXT NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        last_error TEXT,
+        next_attempt_at TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        sent_at TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_notify_queue_due ON notify_queue(status, next_attempt_at);
+    `);
+  }
+
+  enqueueMessage(payload, targets) {
+    const now = nowIso();
+    for (const target of targets) {
+      const dedupeKey = `${payload.msgId}:${target.type}:${target.channel}`;
+      this.db.prepare(`
+        INSERT OR IGNORE INTO notify_queue
+        (dedupe_key, msg_id, channel_type, channel_name, target_json, payload_json, status, attempts, next_attempt_at, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, 'pending', 0, ?, ?, ?)
+      `).run(
+        dedupeKey,
+        payload.msgId,
+        target.type,
+        target.channel,
+        JSON.stringify(target),
+        JSON.stringify(payload),
+        now,
+        now,
+        now,
+      );
+    }
+  }
+
+  claimDue(limit = 50) {
+    return this.db.prepare(`
+      SELECT * FROM notify_queue
+      WHERE status IN ('pending', 'failed') AND next_attempt_at <= ?
+      ORDER BY next_attempt_at ASC
+      LIMIT ?
+    `).all(nowIso(), limit);
+  }
+
+  markSent(id) {
+    this.db.prepare(`
+      UPDATE notify_queue
+      SET status = 'sent', attempts = attempts + 1, updated_at = ?, sent_at = ?, last_error = NULL
+      WHERE id = ?
+    `).run(nowIso(), nowIso(), id);
+  }
+
+  markFailed(id, reason, backoffMs = 5000) {
+    const nextAttemptAt = new Date(Date.now() + backoffMs).toISOString();
+    this.db.prepare(`
+      UPDATE notify_queue
+      SET status = 'failed', attempts = attempts + 1, updated_at = ?, next_attempt_at = ?, last_error = ?
+      WHERE id = ?
+    `).run(nowIso(), nextAttemptAt, reason, id);
+  }
+
+  markDead(id, reason) {
+    this.db.prepare(`
+      UPDATE notify_queue
+      SET status = 'dead', attempts = attempts + 1, updated_at = ?, last_error = ?
+      WHERE id = ?
+    `).run(nowIso(), reason, id);
+  }
+
+  pendingCount() {
+    const row = this.db.prepare(`
+      SELECT COUNT(*) as count FROM notify_queue WHERE status IN ('pending', 'failed')
+    `).get();
+    return Number(row?.count ?? 0);
+  }
+}
+
+const formatNotifyText = (payload) => `📨 [${payload.from}]\n${payload.text}`;
+
+const TG_MAX_LENGTH = 4000; // Telegram limit is 4096, leave margin
+
+const sendTelegram = async (target, payload) => {
+  let text = formatNotifyText(payload);
+
+  // Truncate if too long for Telegram
+  if (text.length > TG_MAX_LENGTH) {
+    text = text.slice(0, TG_MAX_LENGTH - 40) + "\n\n... [truncated, full in DB]";
+  }
+
+  const body = {
+    chat_id: target.chatId,
+    text,
+    disable_web_page_preview: true,
+  };
+  if (target.topicId) body.message_thread_id = Number(target.topicId);
+
+  const res = await fetch(`https://api.telegram.org/bot${target.botToken}/sendMessage`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const errText = await res.text().catch(() => "");
+    const err = new Error(`telegram-http-${res.status}:${errText.slice(0, 280)}`);
+    err.httpStatus = res.status;
+    throw err;
+  }
+};
+
+const sendWebhook = async (target, payload) => {
+  const res = await fetch(target.url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...(target.headers || {}) },
+    body: JSON.stringify(payload),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`webhook-http-${res.status}:${text.slice(0, 280)}`);
+  }
+};
+
+export const dispatchNotification = async (target, payload) => {
+  if (target.type === "telegram") return sendTelegram(target, payload);
+  if (target.type === "webhook") return sendWebhook(target, payload);
+  throw new Error(`unsupported-notify-target:${target.type}`);
+};
+
+export const flushNotifyQueue = async ({ queue, log, limit = 50 }) => {
+  const due = queue.claimDue(limit);
+  for (const row of due) {
+    const target = JSON.parse(String(row.target_json));
+    const payload = JSON.parse(String(row.payload_json));
+
+    log("info", "Notify attempt", {
+      queueId: row.id,
+      msgId: row.msg_id,
+      target: `${row.channel_type}:${row.channel_name}`,
+      attempt: Number(row.attempts) + 1,
+    });
+
+    try {
+      await dispatchNotification(target, payload);
+      queue.markSent(row.id);
+      log("info", "Notify success", {
+        queueId: row.id,
+        msgId: row.msg_id,
+        target: `${row.channel_type}:${row.channel_name}`,
+      });
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      const httpStatus = err instanceof Error ? err.httpStatus : undefined;
+      const attempts = Number(row.attempts) + 1;
+
+      // Dead-letter on permanent failures (4xx) or too many retries
+      if ((httpStatus && httpStatus >= 400 && httpStatus < 500) || attempts >= 10) {
+        queue.markDead(row.id, `permanent: ${reason}`);
+        log("error", "Notify dead-lettered", {
+          queueId: row.id,
+          msgId: row.msg_id,
+          target: `${row.channel_type}:${row.channel_name}`,
+          reason,
+          attempts,
+        });
+      } else {
+        queue.markFailed(row.id, reason, Math.min(60_000, 2_000 * attempts));
+        log("warn", "Notify failed", {
+          queueId: row.id,
+          msgId: row.msg_id,
+          target: `${row.channel_type}:${row.channel_name}`,
+          reason,
+        });
+      }
+    }
+  }
+
+  return due.length;
+};

package/runtime/scripts/runtime-capability.mjs

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+
+const policy = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).engines?.node;
+const minimumPolicy = /^>=(\d+\.\d+\.\d+)$/.exec(policy ?? '');
+if (!minimumPolicy) throw new Error('runtime.node-policy-invalid: engines.node must declare one minimum Node.js version.');
+export const MIN_NODE_VERSION = minimumPolicy[1];
+
+function failure(code, detail) {
+  return Object.assign(new Error(`${code}: ${detail}`), { code });
+}
+
+// Only built-ins and the root policy manifest: no installed workspace modules or
+// profile access before the CLI loads modules that statically import node:sqlite.
+export async function checkRuntime({ version = process.versions.node, loadSqlite = () => import('node:sqlite') } = {}) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  const current = match?.slice(1).map(Number);
+  const minimum = MIN_NODE_VERSION.split('.').map(Number);
+  const difference = current?.findIndex((value, index) => value !== minimum[index]);
+  if (!current || (difference >= 0 && current[difference] < minimum[difference])) {
+    throw failure('runtime.node-version-unsupported', `Use Node.js ${MIN_NODE_VERSION} or newer; current version is ${version}.`);
+  }
+  try {
+    const { DatabaseSync } = await loadSqlite();
+    const db = new DatabaseSync(':memory:');
+    try {
+      if (db.prepare('SELECT 1 AS ok').get().ok !== 1) throw new Error('probe failed');
+    } finally {
+      db.close();
+    }
+  } catch {
+    // Do not expose loader output or an arbitrary error payload in diagnostics.
+    throw failure('runtime.sqlite-unavailable', `Node.js ${MIN_NODE_VERSION} or newer with working node:sqlite is required; current version is ${version}. Remove --no-experimental-sqlite or choose a compatible Node.js installation.`);
+  }
+}

package/runtime/scripts/secure-state.mjs

@@ -0,0 +1,105 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+const currentUid = () => typeof process.getuid === "function" ? process.getuid() : undefined;
+
+const assertOwned = (stats, target) => {
+  const uid = currentUid();
+  if (uid !== undefined && stats.uid !== uid) {
+    throw new Error(`private-state-owner-mismatch:${target}`);
+  }
+};
+
+const assertPrivateDirectory = async (dirPath) => {
+  const stats = await lstat(dirPath);
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    throw new Error(`private-state-directory-invalid:${dirPath}`);
+  }
+  assertOwned(stats, dirPath);
+};
+
+const assertPrivateRegularFile = async (filePath) => {
+  const stats = await lstat(filePath);
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error(`private-state-file-invalid:${filePath}`);
+  }
+  assertOwned(stats, filePath);
+};
+
+export const setPrivateUmask = () => {
+  process.umask(0o077);
+};
+
+export const ensurePrivateDirectory = async (dirPath) => {
+  setPrivateUmask();
+  await mkdir(dirPath, { recursive: true, mode: 0o700 });
+  await assertPrivateDirectory(dirPath);
+  await chmod(dirPath, 0o700);
+};
+
+export const readPrivateJson = async (filePath) => {
+  setPrivateUmask();
+  await assertPrivateDirectory(path.dirname(filePath));
+  await assertPrivateRegularFile(filePath);
+  await chmod(filePath, 0o600);
+
+  const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile()) throw new Error(`private-state-file-invalid:${filePath}`);
+    assertOwned(stats, filePath);
+    return JSON.parse(await handle.readFile("utf8"));
+  } finally {
+    await handle.close();
+  }
+};
+
+export const writePrivateJson = async (filePath, value, { beforeWrite } = {}) => {
+  setPrivateUmask();
+  const dirPath = path.dirname(filePath);
+  await ensurePrivateDirectory(dirPath);
+
+  try {
+    await assertPrivateRegularFile(filePath);
+  } catch (err) {
+    if (err?.code !== "ENOENT") throw err;
+  }
+
+  const tempPath = path.join(
+    dirPath,
+    `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  let handle;
+  try {
+    handle = await open(
+      tempPath,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+      0o600,
+    );
+    await beforeWrite?.(tempPath, handle);
+    await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(tempPath, filePath);
+    await chmod(filePath, 0o600);
+
+    // Windows does not support fsync on a directory handle (FlushFileBuffers
+    // returns EPERM/EINVAL). The file itself is already fsync'd above; the
+    // directory sync is a best-effort durability nicety, so skip it on win32.
+    if (process.platform !== "win32") {
+      const dirHandle = await open(dirPath, constants.O_RDONLY | constants.O_DIRECTORY);
+      try {
+        await dirHandle.sync();
+      } finally {
+        await dirHandle.close();
+      }
+    }
+  } catch (err) {
+    if (handle) await handle.close().catch(() => {});
+    await unlink(tempPath).catch(() => {});
+    throw err;
+  }
+};