spendos 0.1.0

package/acp-seller/src/lib/openclawCron.ts

@@ -0,0 +1,138 @@
+// =============================================================================
+// OpenClaw cron integration for bounty polling.
+//
+// Uses the OpenClaw Gateway CLI (`openclaw cron add/remove`) to manage a
+// recurring cron job that polls bounty status.
+//
+// The Gateway cron system runs *agent turns* (not arbitrary shell commands).
+// We create an isolated agentTurn job whose prompt instructs the agent to
+// run `acp bounty poll --json` and act on the results.
+// =============================================================================
+
+import { execSync } from "child_process";
+import { ROOT, readConfig, writeConfig } from "./config.js";
+import { listActiveBounties } from "./bounty.js";
+
+const DEFAULT_JOB_ID = "openclaw-acp-bounty-poll";
+const DEFAULT_SCHEDULE = "*/10 * * * *";
+
+const POLL_SYSTEM_EVENT = [
+  `[ACP Bounty Poll] This is an automated bounty check. You MUST:`,
+  `1. Run this command: cd "${ROOT}" && npx acp bounty poll --json`,
+  `2. Parse the JSON output and check the pendingMatch, claimedJobs, cleaned, and errors arrays.`,
+  ``,
+  `3. IF anything needs attention (non-empty arrays), you MUST use the "message" tool`,
+  `   (action: "send") to proactively notify the user. Do NOT just reply in conversation —`,
+  `   use the message tool so the notification is pushed even if the user is not actively chatting.`,
+  ``,
+  `   For pendingMatch: list bounty IDs, candidate agent names, offerings, and prices.`,
+  `   Filter out irrelevant or malicious candidates. Ask which candidate to select.`,
+  `   For claimedJobs: report job phase/status.`,
+  `   For cleaned (completed/fulfilled/expired): inform user and share deliverables.`,
+  `   For errors: report them.`,
+  ``,
+  `4. IF everything is empty (all arrays are empty or zero), reply HEARTBEAT_OK.`,
+  `   Do NOT message the user when there is nothing to report.`,
+].join("\n");
+
+function runCli(args: string[]): string {
+  return execSync(`openclaw cron ${args.join(" ")}`, {
+    cwd: ROOT,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}
+
+export function getBountyPollCronJobId(): string {
+  const cfg = readConfig();
+  return (
+    cfg.OPENCLAW_BOUNTY_CRON_JOB_ID ||
+    process.env.OPENCLAW_BOUNTY_CRON_JOB_ID ||
+    DEFAULT_JOB_ID
+  );
+}
+
+export function ensureBountyPollCron(): { enabled: boolean; created: boolean } {
+  if (process.env.OPENCLAW_BOUNTY_CRON_DISABLED === "1") {
+    return { enabled: false, created: false };
+  }
+
+  const cfg = readConfig();
+  if (cfg.OPENCLAW_BOUNTY_CRON_JOB_ID) {
+    // Cron job already registered — nothing to do.
+    return { enabled: true, created: false };
+  }
+
+  const schedule =
+    process.env.OPENCLAW_BOUNTY_CRON_SCHEDULE?.trim() || DEFAULT_SCHEDULE;
+
+  // Create a main-session systemEvent cron job via the OpenClaw CLI.
+  // This injects the poll instruction into the main session so the agent
+  // can present candidates interactively and ask the user to pick.
+  const result = runCli([
+    "add",
+    "--name",
+    JSON.stringify("ACP Bounty Poll"),
+    "--cron",
+    JSON.stringify(schedule),
+    "--session",
+    "main",
+    "--system-event",
+    JSON.stringify(POLL_SYSTEM_EVENT),
+    "--wake",
+    "now",
+  ]);
+
+  // Parse the job id from CLI output (JSON object with "id" field).
+  let jobId: string | undefined;
+  try {
+    const parsed = JSON.parse(result);
+    jobId = parsed.id || parsed.jobId;
+  } catch {
+    // If output isn't JSON, try to extract a UUID-like id.
+    const match = result.match(
+      /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i,
+    );
+    if (match) jobId = match[0];
+  }
+
+  if (!jobId) {
+    throw new Error(
+      `Failed to parse cron job id from OpenClaw CLI output: ${result}`,
+    );
+  }
+
+  writeConfig({ ...cfg, OPENCLAW_BOUNTY_CRON_JOB_ID: jobId });
+  return { enabled: true, created: true };
+}
+
+export function removeBountyPollCronIfUnused(): {
+  enabled: boolean;
+  removed: boolean;
+} {
+  if (process.env.OPENCLAW_BOUNTY_CRON_DISABLED === "1") {
+    return { enabled: false, removed: false };
+  }
+
+  const active = listActiveBounties();
+  if (active.length > 0) {
+    return { enabled: true, removed: false };
+  }
+
+  const cfg = readConfig();
+  const jobId = cfg.OPENCLAW_BOUNTY_CRON_JOB_ID;
+  if (!jobId) {
+    return { enabled: true, removed: false };
+  }
+
+  try {
+    runCli(["remove", jobId]);
+  } catch {
+    // Job may already be gone — that's fine.
+  }
+
+  const next = readConfig();
+  delete next.OPENCLAW_BOUNTY_CRON_JOB_ID;
+  writeConfig(next);
+  return { enabled: true, removed: true };
+}

package/acp-seller/src/lib/output.ts

@@ -0,0 +1,104 @@
+// =============================================================================
+// Dual-mode output: human-friendly (default) vs JSON (--json flag / ACP_JSON=1)
+// With ANSI color support for TTY terminals.
+// =============================================================================
+
+let jsonMode = false;
+
+export function setJsonMode(enabled: boolean): void {
+  jsonMode = enabled;
+}
+
+export function isJsonMode(): boolean {
+  return jsonMode;
+}
+
+// -- ANSI colors (only when stdout is a TTY and not in JSON mode) --
+
+const isTTY = process.stdout.isTTY === true;
+
+const c = {
+  bold: (s: string) => (isTTY && !jsonMode ? `\x1b[1m${s}\x1b[0m` : s),
+  dim: (s: string) => (isTTY && !jsonMode ? `\x1b[2m${s}\x1b[0m` : s),
+  green: (s: string) => (isTTY && !jsonMode ? `\x1b[32m${s}\x1b[0m` : s),
+  red: (s: string) => (isTTY && !jsonMode ? `\x1b[31m${s}\x1b[0m` : s),
+  yellow: (s: string) => (isTTY && !jsonMode ? `\x1b[33m${s}\x1b[0m` : s),
+  cyan: (s: string) => (isTTY && !jsonMode ? `\x1b[36m${s}\x1b[0m` : s),
+};
+
+export { c as colors };
+
+// -- Output functions --
+
+/** Print JSON to stdout (for --json mode or agent consumption). */
+export function json(data: unknown): void {
+  console.log(JSON.stringify(data, null, jsonMode ? undefined : 2));
+}
+
+/** Print a line to stdout (human mode). Suppressed in JSON mode. */
+export function log(msg: string): void {
+  if (!jsonMode) console.log(msg);
+}
+
+/** Print an error line to stderr. Always shown. */
+export function error(msg: string): void {
+  if (jsonMode) {
+    console.error(JSON.stringify({ error: msg }));
+  } else {
+    console.error(c.red(`Error: ${msg}`));
+  }
+}
+
+/** Print a success line (human mode). Suppressed in JSON mode. */
+export function success(msg: string): void {
+  if (!jsonMode) console.log(c.green(`  ${msg}`));
+}
+
+/** Print a warning line (human mode). Suppressed in JSON mode. */
+export function warn(msg: string): void {
+  if (!jsonMode) console.log(c.yellow(`  Warning: ${msg}`));
+}
+
+/** Print a section heading. */
+export function heading(title: string): void {
+  if (!jsonMode) {
+    console.log(`\n${c.bold(title)}`);
+    console.log(c.dim("-".repeat(50)));
+  }
+}
+
+/** Print a key-value pair. */
+export function field(
+  label: string,
+  value: string | number | boolean | null | undefined,
+): void {
+  if (!jsonMode) {
+    console.log(`  ${c.dim(label.padEnd(18))} ${value ?? "-"}`);
+  }
+}
+
+/**
+ * Output data in the appropriate mode.
+ * In JSON mode: prints JSON to stdout.
+ * In human mode: calls the formatter function.
+ */
+export function output(
+  data: unknown,
+  humanFormatter: (data: any) => void,
+): void {
+  if (jsonMode) {
+    json(data);
+  } else {
+    humanFormatter(data);
+  }
+}
+
+/** Fatal error — print and exit. */
+export function fatal(msg: string): never {
+  error(msg);
+  process.exit(1);
+}
+
+export function formatSymbol(symbol: string): string {
+  return symbol[0].startsWith("$") ? symbol : `$${symbol}`;
+}

package/acp-seller/src/lib/wallet.ts

@@ -0,0 +1,81 @@
+// =============================================================================
+// Wallet / agent info retrieval.
+// =============================================================================
+
+import client from "./client.js";
+import { readConfig } from "./config.js";
+
+export interface ActiveAgentInfo {
+  name: string;
+  walletAddress: string;
+}
+
+/**
+ * Require an active agent. Returns { name, walletAddress }.
+ * If no active agent is found, exits with a helpful message telling the
+ * user/agent to run `acp agent list` or `acp agent switch` or `acp setup`.
+ */
+export async function requireActiveAgent(): Promise<ActiveAgentInfo> {
+  // First try the API
+  try {
+    const me = await getMyAgentInfo();
+    const name = me.name?.trim();
+    const walletAddress = me.walletAddress?.trim();
+    if (name && walletAddress) return { name, walletAddress };
+  } catch {
+    // fall through to local config check
+  }
+
+  // Check local config for guidance
+  const config = readConfig();
+  const agents = config.agents ?? [];
+  const active = agents.find((a) => a.active);
+
+  if (active) {
+    // There IS an active agent but the API call failed (likely expired session/key)
+    console.error(
+      `Error: Active agent "${active.name}" found but API call failed. ` +
+        `Session may have expired. Run \`acp login\` to re-authenticate.`,
+    );
+    process.exit(1);
+  }
+
+  if (agents.length > 0) {
+    // Agents exist but none is active — tell them to pick one
+    const names = agents.map((a) => a.name).join(", ");
+    console.error(
+      `Error: No active agent selected. Available agents: ${names}\n` +
+        `Run \`acp agent switch <agent-name>\` to select one.`,
+    );
+    process.exit(1);
+  }
+
+  // No agents at all
+  console.error("Error: No agents configured. Run `acp setup` to create one.");
+  process.exit(1);
+}
+
+export async function getMyAgentInfo(): Promise<{
+  name: string;
+  description: string;
+  tokenAddress: string;
+  token: {
+    name: string;
+    symbol: string;
+  };
+  walletAddress: string;
+  jobs: {
+    name: string;
+    priceV2: {
+      type: string;
+      value: number;
+    };
+    slaMinutes: number;
+    requiredFunds: boolean;
+    deliverable: string;
+    requirement: Record<string, any>;
+  }[];
+}> {
+  const agent = await client.get("/acp/me");
+  return agent.data.data;
+}

package/acp-seller/src/seller/offerings/_shared/preTransactionScan.ts

@@ -0,0 +1,127 @@
+/**
+ * Pre-transaction wallet scan helper.
+ *
+ * Calls the x402janus Guardian API to perform a lightweight wallet risk check
+ * before executing on-chain operations (revokes, approvals, etc.).
+ *
+ * This is an opt-in, non-blocking safety check:
+ *   - Returns `null` on any error (network, timeout, bad response).
+ *   - Logs a warning when the wallet's health score is below 50.
+ *   - Never throws — callers can always ignore the result.
+ *
+ * Enable via environment variable: ACP_PRE_SCAN_ENABLED=true
+ */
+
+const GUARDIAN_API_URL =
+  process.env.GUARDIAN_API_URL || "https://x402janus.com";
+
+const SCAN_TIMEOUT_MS = 20_000;
+
+export interface ScanResult {
+  /** 0-100 health score. Lower means higher risk. */
+  healthScore: number;
+  /** Severity label returned by Guardian (e.g. "low", "medium", "high", "critical"). */
+  severity: string | null;
+  /** Raw analysis payload from Guardian for logging/audit. */
+  raw: Record<string, unknown>;
+}
+
+/**
+ * Check whether pre-transaction scanning is enabled.
+ *
+ * Reads `ACP_PRE_SCAN_ENABLED` at call time so the value can change
+ * between invocations without restarting the process.
+ */
+export function isPreScanEnabled(): boolean {
+  return process.env.ACP_PRE_SCAN_ENABLED === "true";
+}
+
+/**
+ * Run a lightweight Guardian scan on `walletAddress` before executing
+ * an on-chain operation.
+ *
+ * @param walletAddress - The 0x-prefixed wallet address to scan.
+ * @param tier - Scan tier to use. Defaults to `"free"` (the quick tier
+ *               endpoint, which does not require payment).
+ * @returns A {@link ScanResult} on success, or `null` if the scan could
+ *          not be completed for any reason.
+ */
+export async function runPreTransactionScan(
+  walletAddress: string,
+  tier: "free" | "quick" = "free",
+): Promise<ScanResult | null> {
+  try {
+    const scanTier = tier === "free" ? "quick" : tier;
+    const url = `${GUARDIAN_API_URL}/api/guardian/scan/${encodeURIComponent(walletAddress)}?tier=${scanTier}`;
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), SCAN_TIMEOUT_MS);
+
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    if (!response.ok) {
+      console.warn(
+        `[preTransactionScan] Guardian API returned ${response.status} for ${walletAddress} — skipping pre-scan`,
+      );
+      return null;
+    }
+
+    const body: unknown = await response.json();
+
+    if (typeof body !== "object" || body === null) {
+      console.warn(
+        "[preTransactionScan] Unexpected response shape — skipping pre-scan",
+      );
+      return null;
+    }
+
+    const data = body as Record<string, unknown>;
+    const analysis = (data.analysis ?? data) as Record<string, unknown>;
+
+    const healthScore =
+      typeof analysis.overall_score === "number"
+        ? analysis.overall_score
+        : typeof analysis.healthScore === "number"
+          ? analysis.healthScore
+          : null;
+
+    if (healthScore === null) {
+      console.warn(
+        "[preTransactionScan] No health score in response — skipping pre-scan",
+      );
+      return null;
+    }
+
+    const severity =
+      typeof analysis.severity === "string" ? analysis.severity : null;
+
+    const result: ScanResult = { healthScore, severity, raw: data };
+
+    if (healthScore < 50) {
+      console.warn(
+        `[preTransactionScan] HIGH RISK wallet ${walletAddress}: healthScore=${healthScore}, severity=${severity ?? "unknown"}`,
+      );
+    } else {
+      console.log(
+        `[preTransactionScan] Wallet ${walletAddress}: healthScore=${healthScore}, severity=${severity ?? "unknown"}`,
+      );
+    }
+
+    return result;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `[preTransactionScan] Pre-scan failed for ${walletAddress}: ${message} — continuing without scan`,
+    );
+    return null;
+  }
+}

package/acp-seller/src/seller/offerings/canonical-catalog.ts

@@ -0,0 +1,221 @@
+// =============================================================================
+// Canonical offering catalog — single source of truth for ACP offering names,
+// prices, and required fields.
+// =============================================================================
+
+export interface CanonicalOffering {
+  /** Offering name — must match directory name and offering.json name exactly. */
+  name: string;
+  /** Fixed job fee in USDC. */
+  jobFee: number;
+  /** Human-readable price label for logs/docs. */
+  priceLabel: string;
+  /** Fee type for all canonical offerings. */
+  jobFeeType: "fixed";
+  /** Whether additional funds are required beyond the fixed fee. */
+  requiredFunds: boolean;
+}
+
+function roundUsd(value: number): number {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}
+
+function formatPriceLabel(jobFee: number): string {
+  const decimals = jobFee < 0.01 ? 4 : 2;
+  return `$${jobFee.toFixed(decimals)} USDC`;
+}
+
+function parsePositiveNumber(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+  return parsed;
+}
+
+function priceOverrideEnvKey(offeringName: string): string {
+  return `ACP_PRICE_OVERRIDE_${offeringName.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+}
+
+export const CANONICAL_CATALOG: Record<string, CanonicalOffering> = {
+  // -- Active ACP offerings (live) ----------------------------------------
+  x402janus_approvals: {
+    name: "x402janus_approvals",
+    jobFee: 0.01,
+    priceLabel: "$0.01 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  x402janus_revoke: {
+    name: "x402janus_revoke",
+    jobFee: 0.05,
+    priceLabel: "$0.05 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  x402janus_revoke_batch: {
+    name: "x402janus_revoke_batch",
+    jobFee: 0.1,
+    priceLabel: "$0.10 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  // -- Guardian scan tiers ------------------------------------------------
+  x402janus_scan_quick: {
+    name: "x402janus_scan_quick",
+    jobFee: 0.01,
+    priceLabel: "$0.01 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  x402janus_scan: {
+    name: "x402janus_scan",
+    jobFee: 0.05,
+    priceLabel: "$0.05 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  x402janus_scan_standard: {
+    name: "x402janus_scan_standard",
+    jobFee: 0.05,
+    priceLabel: "$0.05 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  x402janus_scan_deep: {
+    name: "x402janus_scan_deep",
+    jobFee: 0.25,
+    priceLabel: "$0.25 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  x402janus_forensic_intelligence: {
+    name: "x402janus_forensic_intelligence",
+    jobFee: 25,
+    priceLabel: "$25.00 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  // -- Compute & training -------------------------------------------------
+  x402janus_experiment_tracking: {
+    name: "x402janus_experiment_tracking",
+    jobFee: 0.1,
+    priceLabel: "$0.10 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  x402janus_gpu_compute: {
+    name: "x402janus_gpu_compute",
+    jobFee: 0.5,
+    priceLabel: "$0.50 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  x402janus_distributed_training: {
+    name: "x402janus_distributed_training",
+    jobFee: 5,
+    priceLabel: "$5.00 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  // -- Multi-tool agent jobs ----------------------------------------------
+  x402janus_multi_tool: {
+    name: "x402janus_multi_tool",
+    jobFee: 5,
+    priceLabel: "$5.00 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  // -- SpendOS autonomous agent services -----------------------------------
+  spendos_summarize_url: {
+    name: "spendos_summarize_url",
+    jobFee: 0.01,
+    priceLabel: "$0.01 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  spendos_tweet_gen: {
+    name: "spendos_tweet_gen",
+    jobFee: 0.01,
+    priceLabel: "$0.01 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  spendos_translate: {
+    name: "spendos_translate",
+    jobFee: 0.02,
+    priceLabel: "$0.02 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  // -- SigilX formal verification services --------------------------------
+  sigilx_verify_proof: {
+    name: "sigilx_verify_proof",
+    jobFee: 2.0,
+    priceLabel: "$2.00 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  sigilx_audit_cert: {
+    name: "sigilx_audit_cert",
+    jobFee: 0.25,
+    priceLabel: "$0.25 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  sigilx_forge_test: {
+    name: "sigilx_forge_test",
+    jobFee: 1.0,
+    priceLabel: "$1.00 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+  sigilx_full_audit: {
+    name: "sigilx_full_audit",
+    jobFee: 5.0,
+    priceLabel: "$5.00 USDC",
+    jobFeeType: "fixed",
+    requiredFunds: false,
+  },
+} as const;
+
+export const CANONICAL_OFFERING_NAMES = Object.keys(
+  CANONICAL_CATALOG,
+) as ReadonlyArray<string>;
+export const EXPECTED_OFFERING_COUNT = CANONICAL_OFFERING_NAMES.length;
+
+export function getCanonicalOfferingNamesForAgent(
+  agentDirName: string,
+): ReadonlyArray<string> {
+  const prefix = `${agentDirName}_`;
+  return CANONICAL_OFFERING_NAMES.filter((name) => name.startsWith(prefix));
+}
+
+export function getEffectiveCanonicalOffering(
+  offeringName: string,
+): CanonicalOffering | undefined {
+  const canonical = CANONICAL_CATALOG[offeringName];
+  if (!canonical) return undefined;
+
+  const explicitOverride = parsePositiveNumber(
+    process.env[priceOverrideEnvKey(offeringName)],
+  );
+  const scopedMultiplier = offeringName.startsWith("sigilx_")
+    ? parsePositiveNumber(process.env.SIGILX_ACP_PRICE_MULTIPLIER)
+    : undefined;
+  const globalMultiplier = parsePositiveNumber(
+    process.env.ACP_PRICE_MULTIPLIER,
+  );
+
+  const multiplier = scopedMultiplier ?? globalMultiplier;
+  const jobFee =
+    explicitOverride ??
+    (multiplier === undefined
+      ? canonical.jobFee
+      : roundUsd(canonical.jobFee * multiplier));
+
+  return {
+    ...canonical,
+    jobFee,
+    priceLabel: formatPriceLabel(jobFee),
+  };
+}

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

@@ -0,0 +1,20 @@
+const SPENDOS_URL = process.env.SPENDOS_URL ?? "https://spendos.xyz";
+
+export async function executeJob(context: any) {
+  const { url } = context.requirement ?? context;
+  if (!url) return { deliverable: 'Error: missing "url" parameter' };
+
+  const res = await fetch(`${SPENDOS_URL}/api/internal/summarize`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ url }),
+  });
+
+  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.summary ?? JSON.stringify(data) };
+}