spendos 0.1.0

package/acp-seller/src/seller/offerings/spendos/spendos_summarize_url/offering.json

@@ -0,0 +1,18 @@
+{
+  "name": "spendos_summarize_url",
+  "description": "AI-powered URL summarization. Send any URL, get a concise summary. Powered by Venice AI with SIWE wallet auth on Base mainnet.",
+  "jobFee": 0.01,
+  "jobFeeType": "fixed",
+  "requiredFunds": false,
+  "requirement": {
+    "type": "object",
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "The URL to summarize"
+      }
+    },
+    "required": ["url"]
+  },
+  "deliverable": "Concise AI summary of the URL content"
+}

package/acp-seller/src/seller/offerings/spendos/spendos_translate/handlers.ts

@@ -0,0 +1,21 @@
+const SPENDOS_URL = process.env.SPENDOS_URL ?? "https://spendos.xyz";
+
+export async function executeJob(context: any) {
+  const { text, language } = context.requirement ?? context;
+  if (!text || !language)
+    return { deliverable: 'Error: missing "text" or "language" parameter' };
+
+  const res = await fetch(`${SPENDOS_URL}/api/internal/jobs/translate`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ text, language }),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    return { deliverable: `Error: ${res.status} ${text.slice(0, 200)}` };
+  }
+
+  const data = (await res.json()) as any;
+  return { deliverable: data.result ?? JSON.stringify(data) };
+}

package/acp-seller/src/seller/offerings/spendos/spendos_translate/offering.json

@@ -0,0 +1,22 @@
+{
+  "name": "spendos_translate",
+  "description": "Translate text to any language using AI. Fast, accurate, cheap.",
+  "jobFee": 0.02,
+  "jobFeeType": "fixed",
+  "requiredFunds": false,
+  "requirement": {
+    "type": "object",
+    "properties": {
+      "text": {
+        "type": "string",
+        "description": "Text to translate"
+      },
+      "language": {
+        "type": "string",
+        "description": "Target language (e.g. Spanish, French, Japanese)"
+      }
+    },
+    "required": ["text", "language"]
+  },
+  "deliverable": "Translated text in the target language"
+}

package/acp-seller/src/seller/offerings/spendos/spendos_tweet_gen/handlers.ts

@@ -0,0 +1,20 @@
+const SPENDOS_URL = process.env.SPENDOS_URL ?? "https://spendos.xyz";
+
+export async function executeJob(context: any) {
+  const { topic } = context.requirement ?? context;
+  if (!topic) return { deliverable: 'Error: missing "topic" parameter' };
+
+  const res = await fetch(`${SPENDOS_URL}/api/internal/jobs/tweet-gen`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ topic }),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    return { deliverable: `Error: ${res.status} ${text.slice(0, 200)}` };
+  }
+
+  const data = (await res.json()) as any;
+  return { deliverable: data.result ?? JSON.stringify(data) };
+}

package/acp-seller/src/seller/offerings/spendos/spendos_tweet_gen/offering.json

@@ -0,0 +1,18 @@
+{
+  "name": "spendos_tweet_gen",
+  "description": "Generate viral crypto tweets from a topic. Returns a punchy 2-3 tweet thread ready to post.",
+  "jobFee": 0.01,
+  "jobFeeType": "fixed",
+  "requiredFunds": false,
+  "requirement": {
+    "type": "object",
+    "properties": {
+      "topic": {
+        "type": "string",
+        "description": "The topic to write tweets about"
+      }
+    },
+    "required": ["topic"]
+  },
+  "deliverable": "Thread of 2-3 crypto tweets"
+}

package/acp-seller/src/seller/runtime/acpSocket.ts

@@ -0,0 +1,413 @@
+// =============================================================================
+// Socket.io client that connects to the ACP backend and dispatches events.
+// =============================================================================
+
+import { io, type Socket } from "socket.io-client";
+import { SocketEvent, type AcpJobEventData } from "./types.js";
+
+const PAGERDUTY_EVENTS_API_URL = "https://events.pagerduty.com/v2/enqueue";
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000;
+const DEFAULT_DISCONNECT_ALERT_THRESHOLD_MS = 2 * 60 * 1000;
+const DEFAULT_DISCONNECT_MONITOR_INTERVAL_MS = 30 * 1000;
+const DEFAULT_MANUAL_RECONNECT_INTERVAL_MS = 5 * 1000;
+const DEFAULT_FAILED_RECONNECTS_BEFORE_ALERT = 3;
+
+type PagerDutyAction = "trigger" | "resolve";
+
+type SocketConnectOptions = {
+  auth: { walletAddress: string };
+  transports: ["websocket"];
+};
+
+export interface SocketLike {
+  connected: boolean;
+  on(event: string, handler: (...args: any[]) => void): unknown;
+  connect(): void;
+  disconnect(): void;
+}
+
+export interface AcpSocketDeps {
+  createSocket?: (acpUrl: string, options: SocketConnectOptions) => SocketLike;
+  fetchFn?: typeof fetch;
+  setIntervalFn?: typeof setInterval;
+  clearIntervalFn?: typeof clearInterval;
+  nowFn?: () => number;
+  heartbeatIntervalMs?: number;
+  disconnectAlertThresholdMs?: number;
+  disconnectMonitorIntervalMs?: number;
+  manualReconnectIntervalMs?: number;
+  failedReconnectsBeforeAlert?: number;
+  pagerDutyRetryDelayMs?: number;
+}
+
+interface PagerDutyOptions {
+  routingKey: string;
+  dedupKey: string;
+  source: string;
+  action: PagerDutyAction;
+  summary: string;
+  severity?: "critical" | "error" | "warning" | "info";
+  details?: Record<string, unknown>;
+  fetchFn: typeof fetch;
+  retryDelayMs?: number;
+  shouldRetry?: () => boolean;
+}
+
+const PAGERDUTY_RETRY_DELAY_MS = 2_000;
+
+async function sendPagerDutyEvent(opts: PagerDutyOptions): Promise<void> {
+  const {
+    routingKey,
+    dedupKey,
+    source,
+    action,
+    summary,
+    severity = "critical",
+    details,
+    fetchFn,
+    retryDelayMs = PAGERDUTY_RETRY_DELAY_MS,
+    shouldRetry,
+  } = opts;
+
+  if (!routingKey) {
+    console.warn(
+      "[socket] PAGERDUTY_ROUTING_KEY not set; skipping PagerDuty event",
+    );
+    return;
+  }
+
+  const payload = {
+    routing_key: routingKey,
+    event_action: action,
+    dedup_key: dedupKey,
+    payload: {
+      summary,
+      source,
+      severity,
+      component: "acp-socket",
+      group: "seller-runtime",
+      class: "socket-connectivity",
+      custom_details: details ?? {},
+    },
+  };
+
+  const attempt = async (): Promise<{ ok: boolean; retryable: boolean }> => {
+    try {
+      const response = await fetchFn(PAGERDUTY_EVENTS_API_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+
+      if (response.ok) {
+        console.log(`[socket] PagerDuty ${action} sent`);
+        return { ok: true, retryable: false };
+      }
+
+      const body = await response.text().catch(() => "<no body>");
+      console.error(
+        `[socket] PagerDuty ${action} failed: ${response.status} ${body}`,
+      );
+
+      // Only retry on server errors (5xx); 4xx are client errors and won't benefit from retry
+      return { ok: false, retryable: response.status >= 500 };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[socket] PagerDuty ${action} error: ${message}`);
+      // Network failures are retryable
+      return { ok: false, retryable: true };
+    }
+  };
+
+  const first = await attempt();
+  if (first.ok || !first.retryable) return;
+
+  if (shouldRetry && !shouldRetry()) {
+    console.log(`[socket] PagerDuty ${action} retry skipped (state changed)`);
+    return;
+  }
+
+  console.log(
+    `[socket] PagerDuty ${action} — retrying in ${retryDelayMs}ms...`,
+  );
+  await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+
+  if (shouldRetry && !shouldRetry()) {
+    console.log(`[socket] PagerDuty ${action} retry aborted (state changed)`);
+    return;
+  }
+
+  await attempt();
+}
+
+export interface AcpSocketCallbacks {
+  onNewTask: (data: AcpJobEventData) => void;
+  onEvaluate?: (data: AcpJobEventData) => void;
+}
+
+export interface AcpSocketOptions {
+  acpUrl: string;
+  walletAddress: string;
+  callbacks: AcpSocketCallbacks;
+}
+
+/**
+ * Connect to the ACP socket and start listening for seller events.
+ * Returns a cleanup function that disconnects the socket.
+ */
+export function connectAcpSocket(
+  opts: AcpSocketOptions,
+  deps: AcpSocketDeps = {},
+): () => void {
+  const { acpUrl, walletAddress, callbacks } = opts;
+
+  const createSocket =
+    deps.createSocket ??
+    ((url: string, options: SocketConnectOptions): SocketLike =>
+      io(url, options) as Socket);
+  const fetchFn = deps.fetchFn ?? fetch;
+  const setIntervalFn = deps.setIntervalFn ?? setInterval;
+  const clearIntervalFn = deps.clearIntervalFn ?? clearInterval;
+  const now = deps.nowFn ?? Date.now;
+
+  const heartbeatIntervalMs =
+    deps.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+  const disconnectAlertThresholdMs =
+    deps.disconnectAlertThresholdMs ?? DEFAULT_DISCONNECT_ALERT_THRESHOLD_MS;
+  const disconnectMonitorIntervalMs =
+    deps.disconnectMonitorIntervalMs ?? DEFAULT_DISCONNECT_MONITOR_INTERVAL_MS;
+  const manualReconnectIntervalMs =
+    deps.manualReconnectIntervalMs ?? DEFAULT_MANUAL_RECONNECT_INTERVAL_MS;
+  const failedReconnectsBeforeAlert =
+    deps.failedReconnectsBeforeAlert ?? DEFAULT_FAILED_RECONNECTS_BEFORE_ALERT;
+  const pagerDutyRetryDelayMs =
+    deps.pagerDutyRetryDelayMs ?? PAGERDUTY_RETRY_DELAY_MS;
+
+  const pdRoutingKey = process.env.PAGERDUTY_ROUTING_KEY ?? "";
+  const pdDedupKey = `acp-socket-${walletAddress.toLowerCase()}`;
+  const pdSource = `openclaw-acp-seller:${walletAddress}`;
+
+  let disconnectedAt: number | null = null;
+  let failedReconnectAttempts = 0;
+  let pdIncidentOpen = false;
+  let reconnectInterval: ReturnType<typeof setInterval> | null = null;
+
+  const socket = createSocket(acpUrl, {
+    auth: { walletAddress },
+    transports: ["websocket"],
+  });
+
+  const triggerPagerDuty = (
+    summary: string,
+    details: Record<string, unknown>,
+  ): void => {
+    if (pdIncidentOpen) return;
+    pdIncidentOpen = true;
+    void sendPagerDutyEvent({
+      routingKey: pdRoutingKey,
+      dedupKey: pdDedupKey,
+      source: pdSource,
+      action: "trigger",
+      summary,
+      severity: "critical",
+      details,
+      fetchFn,
+      retryDelayMs: pagerDutyRetryDelayMs,
+      shouldRetry: () => pdIncidentOpen,
+    });
+  };
+
+  const resolvePagerDuty = (
+    summary: string,
+    details: Record<string, unknown>,
+  ): void => {
+    if (!pdIncidentOpen) return;
+    pdIncidentOpen = false;
+    void sendPagerDutyEvent({
+      routingKey: pdRoutingKey,
+      dedupKey: pdDedupKey,
+      source: pdSource,
+      action: "resolve",
+      summary,
+      severity: "info",
+      details,
+      fetchFn,
+      retryDelayMs: pagerDutyRetryDelayMs,
+    });
+  };
+
+  const stopReconnectLoop = (): void => {
+    if (reconnectInterval) {
+      clearIntervalFn(reconnectInterval);
+      reconnectInterval = null;
+    }
+  };
+
+  const startReconnectLoop = (): void => {
+    if (reconnectInterval) return;
+
+    console.log(
+      `[socket] Server-initiated disconnect — starting manual reconnect loop (${manualReconnectIntervalMs}ms)`,
+    );
+
+    reconnectInterval = setIntervalFn(() => {
+      if (socket.connected) {
+        stopReconnectLoop();
+        return;
+      }
+
+      failedReconnectAttempts += 1;
+      console.log(
+        `[socket] Manual reconnect attempt #${failedReconnectAttempts}`,
+      );
+      socket.connect();
+
+      if (failedReconnectAttempts >= failedReconnectsBeforeAlert) {
+        triggerPagerDuty(
+          `ACP socket failed to reconnect after ${failedReconnectsBeforeAlert} attempts`,
+          {
+            walletAddress,
+            failedReconnectAttempts,
+            acpUrl,
+          },
+        );
+      }
+    }, manualReconnectIntervalMs);
+  };
+
+  socket.on(
+    SocketEvent.ROOM_JOINED,
+    (_data: unknown, callback?: (ack: boolean) => void) => {
+      console.log("[socket] Joined ACP room");
+      if (typeof callback === "function") callback(true);
+    },
+  );
+
+  socket.on(
+    SocketEvent.ON_NEW_TASK,
+    (data: AcpJobEventData, callback?: (ack: boolean) => void) => {
+      if (typeof callback === "function") callback(true);
+      console.log(`[socket] onNewTask  jobId=${data.id}  phase=${data.phase}`);
+      try {
+        callbacks.onNewTask(data);
+      } catch (err) {
+        console.error(
+          `[socket] CRITICAL: onNewTask callback threw synchronously for job ${data.id}:`,
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+    },
+  );
+
+  socket.on(
+    SocketEvent.ON_EVALUATE,
+    (data: AcpJobEventData, callback?: (ack: boolean) => void) => {
+      if (typeof callback === "function") callback(true);
+      console.log(`[socket] onEvaluate  jobId=${data.id}  phase=${data.phase}`);
+      try {
+        if (callbacks.onEvaluate) {
+          callbacks.onEvaluate(data);
+        }
+      } catch (err) {
+        console.error(
+          `[socket] CRITICAL: onEvaluate callback threw synchronously for job ${data.id}:`,
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+    },
+  );
+
+  socket.on("connect", () => {
+    const wasDisconnected = disconnectedAt !== null;
+    let disconnectedMs = 0;
+
+    if (disconnectedAt !== null) {
+      disconnectedMs = now() - disconnectedAt;
+    }
+
+    disconnectedAt = null;
+    failedReconnectAttempts = 0;
+    stopReconnectLoop();
+
+    console.log("[socket] Connected to ACP");
+
+    if (wasDisconnected) {
+      resolvePagerDuty("ACP socket reconnected successfully", {
+        walletAddress,
+        disconnectedMs,
+        acpUrl,
+      });
+    }
+  });
+
+  socket.on("disconnect", (reason) => {
+    console.log(`[socket] Disconnected: ${reason}`);
+    if (disconnectedAt === null) {
+      disconnectedAt = now();
+    }
+
+    // "io server disconnect" = server forcibly closed the connection.
+    // Socket.io will NOT auto-reconnect — we must explicitly reconnect.
+    if (reason === "io server disconnect") {
+      startReconnectLoop();
+    }
+  });
+
+  socket.on("connect_error", (err: Error) => {
+    console.error(`[socket] Connection error: ${err.message}`);
+  });
+
+  const heartbeatInterval = setIntervalFn(() => {
+    if (socket.connected) {
+      console.log("[socket] Heartbeat: connected to ACP");
+      return;
+    }
+
+    const downForMs = disconnectedAt !== null ? now() - disconnectedAt : 0;
+    console.log(
+      `[socket] Heartbeat: disconnected for ${Math.floor(downForMs / 1000)}s`,
+    );
+  }, heartbeatIntervalMs);
+
+  const disconnectMonitor = setIntervalFn(() => {
+    if (disconnectedAt === null) return;
+
+    const downForMs = now() - disconnectedAt;
+    if (downForMs > disconnectAlertThresholdMs) {
+      triggerPagerDuty("ACP socket disconnected for over 2 minutes", {
+        walletAddress,
+        disconnectedForSeconds: Math.floor(downForMs / 1000),
+        acpUrl,
+      });
+    }
+  }, disconnectMonitorIntervalMs);
+
+  let isDisconnected = false;
+
+  const disconnect = () => {
+    if (isDisconnected) return;
+    isDisconnected = true;
+
+    stopReconnectLoop();
+    clearIntervalFn(heartbeatInterval);
+    clearIntervalFn(disconnectMonitor);
+    socket.disconnect();
+    process.off("SIGINT", onSigInt);
+    process.off("SIGTERM", onSigTerm);
+  };
+
+  const onSigInt = () => {
+    disconnect();
+    process.exit(0);
+  };
+
+  const onSigTerm = () => {
+    disconnect();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", onSigInt);
+  process.on("SIGTERM", onSigTerm);
+
+  return disconnect;
+}

package/acp-seller/src/seller/runtime/logger.ts

@@ -0,0 +1,36 @@
+export interface Logger {
+  debug: (message: string, meta?: Record<string, unknown>) => void;
+  info: (message: string, meta?: Record<string, unknown>) => void;
+  warn: (message: string, meta?: Record<string, unknown>) => void;
+  error: (message: string, meta?: Record<string, unknown>) => void;
+}
+
+function formatMessage(
+  level: "debug" | "info" | "warn" | "error",
+  scope: string,
+  message: string,
+  meta?: Record<string, unknown>,
+): string {
+  const prefix = `[${scope}]`;
+  if (!meta || Object.keys(meta).length === 0) {
+    return `${prefix} ${message}`;
+  }
+  return `${prefix} ${message} ${JSON.stringify({ level, ...meta })}`;
+}
+
+export function createLogger(scope: string): Logger {
+  return {
+    debug: (message, meta) => {
+      console.debug(formatMessage("debug", scope, message, meta));
+    },
+    info: (message, meta) => {
+      console.info(formatMessage("info", scope, message, meta));
+    },
+    warn: (message, meta) => {
+      console.warn(formatMessage("warn", scope, message, meta));
+    },
+    error: (message, meta) => {
+      console.error(formatMessage("error", scope, message, meta));
+    },
+  };
+}

package/acp-seller/src/seller/runtime/offeringTypes.ts

@@ -0,0 +1,52 @@
+// =============================================================================
+// Shared types for offering handler contracts.
+// =============================================================================
+
+/** Optional token-transfer instruction returned by an offering handler. */
+export interface TransferInstruction {
+  /** Token contract address (e.g. ERC-20 CA). */
+  ca: string;
+  /** Amount to transfer. */
+  amount: number;
+}
+
+/**
+ * Result returned by an offering's `executeJob` handler.
+ *
+ * - `deliverable` — the job result (simple string or structured object).
+ * - `payableDetail` — optional: instructs the runtime to include a token transfer
+ *                     in the deliver step (e.g. "return money to buyer").
+ */
+export interface ExecuteJobResult {
+  deliverable: string | { type: string; value: unknown };
+  payableDetail?: { amount: number; tokenAddress: string };
+}
+
+/**
+ * Validation result returned by validateRequirements handler.
+ * Can be a simple boolean (backwards compatible) or an object with valid flag and optional reason.
+ */
+export type ValidationResult = boolean | { valid: boolean; reason?: string };
+
+/**
+ * The handler set every offering must / can export.
+ *
+ * Required:
+ *   executeJob(request) => ExecuteJobResult
+ *
+ * Optional:
+ *   validateRequirements(request) => boolean | { valid: boolean, reason?: string }
+ *   requestPayment(request) => string
+ *   requestAdditionalFunds(request) => { content, amount, tokenAddress, recipient }
+ */
+export interface OfferingHandlers {
+  executeJob: (request: Record<string, any>) => Promise<ExecuteJobResult>;
+  validateRequirements?: (request: Record<string, any>) => ValidationResult;
+  requestPayment?: (request: Record<string, any>) => string;
+  requestAdditionalFunds?: (request: Record<string, any>) => {
+    content?: string;
+    amount: number;
+    tokenAddress: string;
+    recipient: string;
+  };
+}