nemoris 0.1.0

package/src/runtime/delivery-ack.js

@@ -0,0 +1,195 @@
+/**
+ * delivery-ack.js — Delivery acknowledgement layer for the Nemoris interaction layer.
+ * Handles criticality classification, guaranteed send pipeline, and pending decision sweeps.
+ */
+
+/**
+ * Classify a response's criticality based on explicit tags or contextual signals.
+ * @param {string} responseText
+ * @param {object} context
+ * @returns {"info"|"result"|"decision_required"}
+ */
+export function classifyCriticality(responseText, context = {}) {
+  // Explicit tag takes highest priority
+  const tagMatch = responseText.match(/\[criticality:(info|result|decision_required)\]/);
+  if (tagMatch) return tagMatch[1];
+
+  // Escalation/timeout/error-recovery + question → decision_required
+  if (
+    (context.isEscalation || context.isTimeout || context.isErrorRecovery) &&
+    responseText.trimEnd().endsWith("?")
+  ) {
+    return "decision_required";
+  }
+
+  // Task completion or failure → result
+  if (context.taskCompleted || context.taskFailed) {
+    return "result";
+  }
+
+  return "info";
+}
+
+export class DeliveryAck {
+  constructor(db, envelopeStore) {
+    this.db = db;
+    this.envelopes = envelopeStore;
+    this._ensureSchema();
+  }
+
+  _ensureSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS pending_decisions (
+        envelope_id     TEXT PRIMARY KEY,
+        chat_id         TEXT NOT NULL,
+        delivered_at    TEXT NOT NULL,
+        timeout_minutes INTEGER NOT NULL DEFAULT 15,
+        re_pinged       INTEGER NOT NULL DEFAULT 0,
+        parked          INTEGER NOT NULL DEFAULT 0
+      );
+    `);
+  }
+
+  /**
+   * Returns all pending_decisions rows that have not been parked.
+   */
+  listPendingDecisions() {
+    return this.db.prepare("SELECT * FROM pending_decisions WHERE parked = 0").all();
+  }
+
+  /**
+   * Send a message with guaranteed delivery, retrying on failure.
+   * On success: marks envelope as delivered, optionally inserts into pending_decisions.
+   * On all retries exhausted: marks envelope as dead_letter.
+   *
+   * @param {object} opts
+   * @param {string} opts.sourceAgent
+   * @param {string} opts.criticality
+   * @param {object} opts.payload
+   * @param {string} opts.chatId
+   * @param {function} opts.sendFn  — async (payload) => messageId
+   * @param {string|null} [opts.correlationId]
+   * @param {number[]} [opts.retryDelays]  — delays in ms between attempts
+   * @returns {Promise<{envelopeId: string, messageId?: string, delivered: boolean, error?: Error}>}
+   */
+  async sendWithGuarantee({
+    sourceAgent,
+    criticality,
+    payload,
+    chatId,
+    sendFn,
+    correlationId = null,
+    retryDelays = [2000, 8000, 32000],
+  }) {
+    const envelope = this.envelopes.create({
+      sourceAgent,
+      criticality,
+      payloadType: "delivery",
+      payload,
+      correlationId,
+    });
+
+    let lastError = null;
+
+    for (let attempt = 0; attempt < retryDelays.length; attempt++) {
+      if (attempt > 0 && retryDelays[attempt - 1] > 0) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelays[attempt - 1]));
+      }
+
+      try {
+        const messageId = await sendFn(payload);
+        this.envelopes.updateAck(envelope.id, "delivered");
+
+        if (criticality === "decision_required") {
+          const now = new Date().toISOString();
+          this.db.prepare(`
+            INSERT OR REPLACE INTO pending_decisions (envelope_id, chat_id, delivered_at, timeout_minutes, re_pinged, parked)
+            VALUES (?, ?, ?, 15, 0, 0)
+          `).run(envelope.id, chatId, now);
+        }
+
+        return { envelopeId: envelope.id, messageId, delivered: true };
+      } catch (err) {
+        lastError = err;
+      }
+    }
+
+    // All retries exhausted
+    this.envelopes.updateAck(envelope.id, "dead_letter");
+    return { envelopeId: envelope.id, delivered: false, error: lastError };
+  }
+
+  /**
+   * Sweep pending decisions: re-ping after timeout, park after double timeout.
+   *
+   * @param {object} opts
+   * @param {Date} [opts.now]
+   * @param {function} opts.sendFn — async (message) => void
+   * @returns {Promise<{rePinged: number, parked: number}>}
+   */
+  async sweepPendingDecisions({ now = new Date(), sendFn }) {
+    const rows = this.db.prepare(`
+      SELECT pd.*, e.payload
+      FROM pending_decisions pd
+      JOIN envelopes e ON e.id = pd.envelope_id
+      WHERE pd.parked = 0
+    `).all();
+
+    let rePinged = 0;
+    let parked = 0;
+
+    for (const row of rows) {
+      const deliveredAt = new Date(row.delivered_at);
+      const elapsedMs = now.getTime() - deliveredAt.getTime();
+      const elapsedMinutes = elapsedMs / 60000;
+
+      if (elapsedMinutes >= row.timeout_minutes * 2 && row.re_pinged === 1) {
+        // Park it
+        this.db.prepare("UPDATE pending_decisions SET parked = 1 WHERE envelope_id = ?").run(row.envelope_id);
+        this.envelopes.updateAck(row.envelope_id, "dead_letter");
+        parked++;
+      } else if (elapsedMinutes >= row.timeout_minutes && row.re_pinged === 0) {
+        // Re-ping
+        let payloadText = "";
+        try {
+          const parsed = JSON.parse(row.payload);
+          payloadText = parsed.text || parsed.message || JSON.stringify(parsed);
+        } catch {
+          payloadText = String(row.payload);
+        }
+        const excerpt = payloadText.slice(0, 100);
+        await sendFn(`Still need your input on this when you get a chance (re: ${excerpt})`);
+        this.db.prepare("UPDATE pending_decisions SET re_pinged = 1 WHERE envelope_id = ?").run(row.envelope_id);
+        rePinged++;
+      }
+    }
+
+    return { rePinged, parked };
+  }
+
+  /**
+   * Clear pending decisions when the operator sends a message, using a timestamp guard.
+   * Marks matching envelopes as "responded" and removes them from pending_decisions.
+   *
+   * @param {string} chatId
+   * @param {string} operatorTimestamp — ISO string; only clears decisions delivered before this
+   * @returns {number} count of cleared decisions
+   */
+  clearPendingDecisions(chatId, operatorTimestamp) {
+    const rows = this.db.prepare(`
+      SELECT envelope_id FROM pending_decisions
+      WHERE chat_id = ? AND delivered_at < ? AND parked = 0
+    `).all(chatId, operatorTimestamp);
+
+    for (const row of rows) {
+      this.envelopes.updateAck(row.envelope_id, "responded");
+    }
+
+    const result = this.db.prepare(`
+      DELETE FROM pending_decisions
+      WHERE chat_id = ? AND delivered_at < ? AND parked = 0
+    `).run(chatId, operatorTimestamp);
+
+    return result.changes;
+  }
+}

package/src/runtime/delivery-adapters/local-file.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+import { writeJson } from "../../utils/fs.js";
+
+function timestampKey() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+export class LocalFileDeliveryAdapter {
+  static adapterId = "local_file";
+
+  constructor({ stateRoot } = {}) {
+    this.stateRoot = stateRoot;
+  }
+
+  async deliver(notification, context = {}) {
+    const target = context.target || notification.target || {};
+    const bucket =
+      target.mode === "peer_agent"
+        ? `peer-${target.peerId || "unknown"}`
+        : String(target.mode || context.profileName || "operator").replace(/[^a-z0-9_-]+/gi, "-");
+    const filePath = path.join(this.stateRoot, "outbox", bucket, `${timestampKey()}.json`);
+    const payload = {
+      timestamp: new Date().toISOString(),
+      profile: context.profileName || null,
+      target,
+      jobId: notification.jobId,
+      stage: notification.stage,
+      message: notification.message || ""
+    };
+
+    await writeJson(filePath, payload);
+
+    return {
+      status: "stored",
+      adapter: LocalFileDeliveryAdapter.adapterId,
+      filePath,
+      bucket,
+      target
+    };
+  }
+}

package/src/runtime/delivery-adapters/openclaw-cli.js

@@ -0,0 +1,94 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+function readFlag(name) {
+  const raw = process.env[name];
+  return raw === "1" || raw === "true";
+}
+
+function parseJson(text) {
+  try {
+    return JSON.parse(String(text || "").trim() || "null");
+  } catch {
+    return {
+      raw: String(text || "")
+    };
+  }
+}
+
+export class OpenClawCliDeliveryAdapter {
+  static adapterId = "openclaw_cli";
+
+  constructor({ execFileImpl } = {}) {
+    this.execFileImpl = execFileImpl || execFileAsync;
+  }
+
+  async deliver(notification, context = {}) {
+    const profile = context.profileConfig || {};
+    const dryRun = profile.dryRun === true;
+
+    if (!dryRun && !readFlag("NEMORIS_ALLOW_GATEWAY_DELIVERY")) {
+      throw new Error("Gateway delivery disabled. Set NEMORIS_ALLOW_GATEWAY_DELIVERY=1 to enable live gateway delivery.");
+    }
+
+    const channel = profile.channel;
+    const target = profile.chatId || profile.target;
+    if (!channel) {
+      throw new Error("OpenClaw CLI delivery profile is missing channel.");
+    }
+    if (!target) {
+      throw new Error("OpenClaw CLI delivery profile is missing target/chatId.");
+    }
+
+    const args = [
+      "message",
+      "send",
+      "--channel",
+      String(channel),
+      "--target",
+      String(target),
+      "--message",
+      String(notification.message || ""),
+      "--json"
+    ];
+
+    if (profile.accountId) {
+      args.push("--account", String(profile.accountId));
+    }
+    if (profile.threadId) {
+      args.push("--thread-id", String(profile.threadId));
+    }
+    if (profile.replyTo) {
+      args.push("--reply-to", String(profile.replyTo));
+    }
+    if (profile.silent !== false) {
+      args.push("--silent");
+    }
+    if (dryRun) {
+      args.push("--dry-run");
+    }
+
+    const { stdout } = await this.execFileImpl("openclaw", args, {
+      timeout: Number(profile.timeoutMs || 10000),
+      maxBuffer: 512 * 1024
+    });
+
+    return {
+      status: dryRun ? "gateway_dry_run" : "gateway_sent",
+      adapter: OpenClawCliDeliveryAdapter.adapterId,
+      target: {
+        mode: channel,
+        chatId: target,
+        accountId: profile.accountId || null
+      },
+      profile: context.profileName || null,
+      command: {
+        bin: "openclaw",
+        args
+      },
+      response: parseJson(stdout)
+    };
+  }
+}

package/src/runtime/delivery-adapters/openclaw-peer.js

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+function readFlag(name) {
+  const raw = process.env[name];
+  return raw === "1" || raw === "true";
+}
+
+function parseJson(text) {
+  try {
+    return JSON.parse(String(text || "").trim() || "null");
+  } catch {
+    return {
+      raw: String(text || "")
+    };
+  }
+}
+
+export class OpenClawPeerDeliveryAdapter {
+  static adapterId = "openclaw_peer";
+
+  constructor({ execFileImpl } = {}) {
+    this.execFileImpl = execFileImpl || execFileAsync;
+  }
+
+  async deliver(notification, context = {}) {
+    const profile = context.profileConfig || {};
+    const target = context.target || {};
+    const dryRun = profile.dryRun === true;
+
+    if (!dryRun && !readFlag("NEMORIS_ALLOW_PEER_DELIVERY")) {
+      throw new Error("Peer delivery disabled. Set NEMORIS_ALLOW_PEER_DELIVERY=1 to enable live peer delivery.");
+    }
+
+    const sessionKey = target.sessionKey || profile.sessionKey;
+    if (!sessionKey) {
+      throw new Error("Peer delivery requires a sessionKey.");
+    }
+
+    if (dryRun) {
+      return {
+        status: "peer_preview",
+        adapter: OpenClawPeerDeliveryAdapter.adapterId,
+        profile: context.profileName || null,
+        peerId: target.peerId || null,
+        sessionKey,
+        command: {
+          bin: "openclaw",
+          args: [
+            "agent",
+            "--message",
+            String(notification.message || ""),
+            "--session-id",
+            String(sessionKey),
+            "--json"
+          ]
+        },
+        response: {
+          ok: true,
+          preview: true
+        }
+      };
+    }
+
+    const args = [
+      "agent",
+      "--message",
+      String(notification.message || ""),
+      "--session-id",
+      String(sessionKey),
+      "--json"
+    ];
+
+    if (profile.agentId) {
+      args.push("--agent", String(profile.agentId));
+    }
+
+    const { stdout } = await this.execFileImpl("openclaw", args, {
+      timeout: Number(profile.timeoutMs || 15000),
+      maxBuffer: 1024 * 1024
+    });
+
+    return {
+      status: dryRun ? "peer_preview" : "peer_sent",
+      adapter: OpenClawPeerDeliveryAdapter.adapterId,
+      profile: context.profileName || null,
+      peerId: target.peerId || null,
+      sessionKey,
+      command: {
+        bin: "openclaw",
+        args
+      },
+      response: parseJson(stdout)
+    };
+  }
+}

package/src/runtime/delivery-adapters/shadow.js

@@ -0,0 +1,13 @@
+export class ShadowDeliveryAdapter {
+  static adapterId = "shadow";
+
+  async deliver(notification, context = {}) {
+    return {
+      status: "shadowed",
+      adapter: ShadowDeliveryAdapter.adapterId,
+      target: notification.target,
+      message: notification.message,
+      profile: context.profileName || null
+    };
+  }
+}

package/src/runtime/delivery-adapters/standalone-http.js

@@ -0,0 +1,98 @@
+import { OUTBOUND_ADDRESS_POLICY } from "../../security/ssrf-check.js";
+import { fetchWithOutboundPolicy } from "../ssrf.js";
+
+function readFlag(name) {
+  const raw = process.env[name];
+  return raw === "1" || raw === "true";
+}
+
+export class StandaloneHttpDeliveryAdapter {
+  static adapterId = "standalone_http";
+
+  constructor({ fetchImpl } = {}) {
+    this.fetchImpl = fetchImpl || globalThis.fetch;
+  }
+
+  async deliver(notification, context = {}) {
+    if (!this.fetchImpl) {
+      throw new Error("No fetch implementation available for standalone HTTP delivery.");
+    }
+
+    const profile = context.profileConfig || {};
+    const dryRun = profile.dryRun === true;
+    const baseUrl = String(profile.baseUrl || "").replace(/\/$/, "");
+    if (!baseUrl) {
+      throw new Error("Standalone HTTP delivery profile is missing baseUrl.");
+    }
+
+    if (!dryRun && !readFlag("NEMORIS_ALLOW_STANDALONE_HTTP_DELIVERY")) {
+      throw new Error("Standalone HTTP delivery disabled. Set NEMORIS_ALLOW_STANDALONE_HTTP_DELIVERY=1 to enable live sends.");
+    }
+
+    const headers = {
+      "content-type": "application/json"
+    };
+    const tokenEnv = profile.authTokenEnv || null;
+    const token = tokenEnv ? process.env[tokenEnv] || null : null;
+    if (token) {
+      headers.authorization = `Bearer ${token}`;
+    }
+
+    const payload = {
+      timestamp: new Date().toISOString(),
+      jobId: notification.jobId,
+      stage: notification.stage,
+      status: notification.status || "ready",
+      profile: context.profileName || null,
+      target: context.target || notification.target || null,
+      message: notification.message || ""
+    };
+
+    if (dryRun) {
+      return {
+        status: "http_preview",
+        adapter: StandaloneHttpDeliveryAdapter.adapterId,
+        endpoint: `${baseUrl}/messages`,
+        payload
+      };
+    }
+
+    // Standalone delivery is operator-configured. Allow loopback for the local
+    // transport server, but block other private/reserved destinations.
+    const response = await fetchWithOutboundPolicy(
+      `${baseUrl}/messages`,
+      {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: typeof AbortSignal?.timeout === "function" ? AbortSignal.timeout(Number(profile.timeoutMs || 5000)) : undefined
+      },
+      {
+        fetchImpl: this.fetchImpl,
+        surface: "standalone_http_delivery",
+        addressPolicy: OUTBOUND_ADDRESS_POLICY.BLOCK_PRIVATE,
+        allowLoopbackAddresses: true,
+        privateAddressMessage: `Standalone HTTP delivery blocked — target resolves to a private/reserved IP address for ${baseUrl}.`,
+      }
+    );
+    const text = await response.text();
+    let data;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      data = { raw: text };
+    }
+
+    if (!response.ok) {
+      throw new Error(`Standalone HTTP delivery failed with ${response.status}: ${typeof data === "string" ? data : JSON.stringify(data)}`);
+    }
+
+    return {
+      status: "http_sent",
+      adapter: StandaloneHttpDeliveryAdapter.adapterId,
+      endpoint: `${baseUrl}/messages`,
+      payload,
+      response: data
+    };
+  }
+}

package/src/runtime/delivery-adapters/telegram.js

@@ -0,0 +1,104 @@
+import { getDaemonEnv } from "../../onboarding/platform.js";
+
+function readFlag(name) {
+  const raw = process.env[name];
+  return raw === "1" || raw === "true";
+}
+
+export async function resolveSecretValue(name, { execFileImpl, platform } = {}) {
+  return getDaemonEnv(name, { execFileImpl, platform });
+}
+
+export class TelegramDeliveryAdapter {
+  static adapterId = "telegram";
+
+  constructor({ fetchImpl, secretResolver, execFileImpl } = {}) {
+    this.fetchImpl = fetchImpl || globalThis.fetch;
+    this.secretResolver =
+      secretResolver ||
+      ((name) =>
+        resolveSecretValue(name, {
+          execFileImpl
+        }));
+  }
+
+  requireFetch() {
+    if (!this.fetchImpl) {
+      throw new Error("Telegram delivery requires fetch support.");
+    }
+  }
+
+  async deliver(notification, context = {}) {
+    this.requireFetch();
+
+    if (!readFlag("NEMORIS_ALLOW_TELEGRAM_DELIVERY")) {
+      throw new Error("Telegram delivery disabled. Set NEMORIS_ALLOW_TELEGRAM_DELIVERY=1 to enable live delivery.");
+    }
+
+    const profile = context.profileConfig || {};
+    const tokenEnv = profile.botTokenEnv;
+    const secret = await this.secretResolver(tokenEnv);
+    const token = secret.value;
+    if (!token) {
+      throw new Error(
+        `Missing Telegram bot token env ${tokenEnv || "(unset profile token env)"} in process env or daemon config.`
+      );
+    }
+
+    // Use notification's chatId for interactive (Telegram-sourced) jobs,
+    // fall back to static profile chatId for scheduled job delivery.
+    const chatId = (notification.source === "telegram" && notification.chatId)
+      ? notification.chatId
+      : profile.chatId;
+    if (!chatId) {
+      throw new Error("Telegram delivery profile is missing chatId.");
+    }
+
+    // Split long messages and send with delay between chunks
+    const { splitTelegramMessage } = await import("../telegram-inbound.js");
+    const chunks = splitTelegramMessage(notification.message);
+    let lastResponse;
+
+    for (let i = 0; i < chunks.length; i++) {
+      if (i > 0) {
+        await new Promise((resolve) => setTimeout(resolve, 250)); // 250ms delay between chunks
+      }
+      const url = `https://api.telegram.org/bot${token}/sendMessage`;
+      lastResponse = await this.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({
+          chat_id: chatId,
+          text: chunks[i],
+        })
+      });
+    }
+
+    const response = lastResponse;
+
+    const raw = await response.text();
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      parsed = raw;
+    }
+
+    if (!response.ok) {
+      throw new Error(`Telegram delivery failed with status ${response.status}`);
+    }
+
+    return {
+      status: "sent",
+      adapter: TelegramDeliveryAdapter.adapterId,
+      authSource: secret.source,
+      target: {
+        mode: "telegram",
+        chatId
+      },
+      response: parsed
+    };
+  }
+}