spendos 0.1.0

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

@@ -0,0 +1,71 @@
+// =============================================================================
+// Seller API calls — accept/reject, request payment, deliver.
+// =============================================================================
+
+import client from "../../lib/client.js";
+
+// -- Accept / Reject --
+
+export interface AcceptOrRejectParams {
+  accept: boolean;
+  reason?: string;
+}
+
+export async function acceptOrRejectJob(
+  jobId: number,
+  params: AcceptOrRejectParams,
+): Promise<void> {
+  console.log(
+    `[sellerApi] acceptOrRejectJob  jobId=${jobId}  accept=${
+      params.accept
+    }  reason=${params.reason ?? "(none)"}`,
+  );
+
+  await client.post(`/acp/providers/jobs/${jobId}/accept`, params);
+}
+
+// -- Payment request --
+
+export interface RequestPaymentParams {
+  content: string;
+  payableDetail?: {
+    amount: number;
+    tokenAddress: string;
+    recipient: string;
+  };
+}
+
+export async function requestPayment(
+  jobId: number,
+  params: RequestPaymentParams,
+): Promise<void> {
+  await client.post(`/acp/providers/jobs/${jobId}/requirement`, params);
+}
+
+// -- Deliver --
+
+export interface DeliverJobParams {
+  deliverable: string | { type: string; value: unknown };
+  payableDetail?: {
+    amount: number;
+    tokenAddress: string;
+  };
+}
+
+export async function deliverJob(
+  jobId: number,
+  params: DeliverJobParams,
+): Promise<void> {
+  const delivStr =
+    typeof params.deliverable === "string"
+      ? params.deliverable
+      : JSON.stringify(params.deliverable);
+  const transferStr = params.payableDetail
+    ? `  transfer: ${params.payableDetail.amount} @ ${params.payableDetail.tokenAddress}`
+    : "";
+  console.log(
+    `[sellerApi] deliverJob  jobId=${jobId}  deliverable=${delivStr}${transferStr}`,
+  );
+
+  return await client.post(`/acp/providers/jobs/${jobId}/deliverable`, params);
+}

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

@@ -0,0 +1,270 @@
+// =============================================================================
+// Startup validation for seller runtime.
+// Validates required environment variables and offering modules before starting.
+// =============================================================================
+
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { listOfferings } from "./offerings.js";
+import { createLogger } from "./logger.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const logger = createLogger("startup");
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+interface EnvVarCheck {
+  name: string;
+  required: boolean;
+  description: string;
+}
+
+/**
+ * Environment variables required or recommended for seller runtime.
+ */
+const ENV_VARS: EnvVarCheck[] = [
+  {
+    name: "LITE_AGENT_API_KEY",
+    required: true,
+    description: "API key for authenticating with ACP backend",
+  },
+  {
+    name: "ACP_SOCKET_URL",
+    required: false,
+    description: "WebSocket URL for ACP backend (defaults to production)",
+  },
+  {
+    name: "PAGERDUTY_ROUTING_KEY",
+    required: false,
+    description: "PagerDuty routing key for critical alerts",
+  },
+  {
+    name: "GUARDIAN_INTERNAL_API_TOKEN",
+    required: true,
+    description:
+      "Internal API token for Guardian scan offerings (HMAC signing)",
+  },
+  {
+    name: "NEXT_PUBLIC_SUPABASE_URL",
+    required: false,
+    description: "Supabase URL for database operations",
+  },
+  {
+    name: "SUPABASE_SERVICE_ROLE_KEY",
+    required: false,
+    description: "Supabase service role key for database operations",
+  },
+];
+
+/**
+ * Validate environment variables are set correctly.
+ */
+function validateEnvironmentVariables(): {
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  for (const envVar of ENV_VARS) {
+    const value = process.env[envVar.name];
+
+    if (!value || value.trim() === "") {
+      if (envVar.required) {
+        errors.push(
+          `Missing required environment variable: ${envVar.name} (${envVar.description})`,
+        );
+      } else {
+        warnings.push(
+          `Optional environment variable not set: ${envVar.name} (${envVar.description})`,
+        );
+      }
+    } else {
+      logger.debug(`Environment variable validated`, { envVar: envVar.name });
+    }
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Validate that offering modules exist and are loadable for the given agent.
+ */
+function validateOfferings(agentDirName: string): {
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  try {
+    const offerings = listOfferings(agentDirName);
+
+    if (offerings.length === 0) {
+      warnings.push(
+        `No offerings found for agent "${agentDirName}". Seller will not accept any jobs.`,
+      );
+      return { errors, warnings };
+    }
+
+    logger.info(`Validating ${offerings.length} offering(s)`, {
+      agentDirName,
+      offeringCount: offerings.length,
+    });
+
+    // Validate each offering has required files
+    const offeringsRoot = path.resolve(
+      __dirname,
+      "..",
+      "offerings",
+      agentDirName,
+    );
+
+    for (const offering of offerings) {
+      const offeringDir = path.join(offeringsRoot, offering);
+      const configPath = path.join(offeringDir, "offering.json");
+      const handlersPath = path.join(offeringDir, "handlers.ts");
+
+      if (!fs.existsSync(configPath)) {
+        errors.push(
+          `Offering "${offering}" missing offering.json at ${configPath}`,
+        );
+      }
+
+      if (!fs.existsSync(handlersPath)) {
+        errors.push(
+          `Offering "${offering}" missing handlers.ts at ${handlersPath}`,
+        );
+      }
+
+      // Try to parse offering.json
+      if (fs.existsSync(configPath)) {
+        try {
+          const content = fs.readFileSync(configPath, "utf-8");
+          const config = JSON.parse(content);
+
+          if (!config.name) {
+            errors.push(
+              `Offering "${offering}" offering.json missing required field: name`,
+            );
+          }
+        } catch (err) {
+          errors.push(
+            `Offering "${offering}" offering.json is not valid JSON: ${err}`,
+          );
+        }
+      }
+    }
+  } catch (err) {
+    errors.push(
+      `Failed to validate offerings: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Validate Node.js version meets minimum requirements.
+ */
+function validateNodeVersion(): { errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const nodeVersion = process.version;
+  const majorVersion = parseInt(nodeVersion.slice(1).split(".")[0], 10);
+
+  logger.debug(`Node.js version detected`, { nodeVersion, majorVersion });
+
+  if (majorVersion < 18) {
+    errors.push(
+      `Node.js version ${nodeVersion} is too old. Minimum required: v18.0.0`,
+    );
+  } else if (majorVersion < 20) {
+    warnings.push(
+      `Node.js version ${nodeVersion} is supported but v20+ is recommended`,
+    );
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Run all startup validations.
+ * Returns a validation result with errors and warnings.
+ */
+export function validateStartup(agentDirName: string): ValidationResult {
+  logger.info("Running startup validation", { agentDirName });
+
+  const allErrors: string[] = [];
+  const allWarnings: string[] = [];
+
+  // 1. Validate Node version
+  const nodeCheck = validateNodeVersion();
+  allErrors.push(...nodeCheck.errors);
+  allWarnings.push(...nodeCheck.warnings);
+
+  // 2. Validate environment variables
+  const envCheck = validateEnvironmentVariables();
+  allErrors.push(...envCheck.errors);
+  allWarnings.push(...envCheck.warnings);
+
+  // 3. Validate offerings
+  const offeringCheck = validateOfferings(agentDirName);
+  allErrors.push(...offeringCheck.errors);
+  allWarnings.push(...offeringCheck.warnings);
+
+  const valid = allErrors.length === 0;
+
+  if (!valid) {
+    logger.error("Startup validation failed", {
+      errorCount: allErrors.length,
+      warningCount: allWarnings.length,
+    });
+
+    for (const error of allErrors) {
+      logger.error(`  - ${error}`);
+    }
+  } else {
+    logger.info("Startup validation passed", {
+      warningCount: allWarnings.length,
+    });
+  }
+
+  if (allWarnings.length > 0) {
+    logger.warn(`Startup validation warnings (${allWarnings.length})`);
+    for (const warning of allWarnings) {
+      logger.warn(`  - ${warning}`);
+    }
+  }
+
+  return {
+    valid,
+    errors: allErrors,
+    warnings: allWarnings,
+  };
+}
+
+/**
+ * Run startup validation and exit if it fails.
+ */
+export function validateStartupOrExit(agentDirName: string): void {
+  const result = validateStartup(agentDirName);
+
+  if (!result.valid) {
+    logger.error(
+      "Fatal: Startup validation failed. Cannot start seller runtime.",
+      {
+        errorCount: result.errors.length,
+      },
+    );
+    process.exit(1);
+  }
+}

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

@@ -0,0 +1,62 @@
+// =============================================================================
+// Minimal ACP types for the seller runtime.
+// Standalone — no imports from @virtuals-protocol/acp-node.
+// =============================================================================
+
+/** Job lifecycle phases (mirrors AcpJobPhases from acp-node). */
+export enum AcpJobPhase {
+  REQUEST = 0,
+  NEGOTIATION = 1,
+  TRANSACTION = 2,
+  EVALUATION = 3,
+  COMPLETED = 4,
+  REJECTED = 5,
+  EXPIRED = 6,
+}
+
+/** Memo types attached to a job (mirrors MemoType from acp-node). */
+export enum MemoType {
+  MESSAGE = 0,
+  CONTEXT_URL = 1,
+  IMAGE_URL = 2,
+  VOICE_URL = 3,
+  OBJECT_URL = 4,
+  TXHASH = 5,
+  PAYABLE_REQUEST = 6,
+  PAYABLE_TRANSFER = 7,
+  PAYABLE_FEE = 8,
+  PAYABLE_FEE_REQUEST = 9,
+}
+
+/** Shape of a single memo as received from the ACP socket/API. */
+export interface AcpMemoData {
+  id: number;
+  memoType: MemoType;
+  content: string;
+  nextPhase: AcpJobPhase;
+  expiry?: string | null;
+  createdAt?: string;
+  type?: string;
+}
+
+/** Shape of the job payload delivered via socket `onNewTask` / `onEvaluate`. */
+export interface AcpJobEventData {
+  id: number;
+  phase: AcpJobPhase;
+  clientAddress: string;
+  providerAddress: string;
+  evaluatorAddress: string;
+  price: number;
+  memos: AcpMemoData[];
+  context: Record<string, any>;
+  createdAt?: string;
+  /** The memo id the seller is expected to sign (if any). */
+  memoToSign?: number;
+}
+
+/** Socket event names used by the ACP backend. */
+export enum SocketEvent {
+  ROOM_JOINED = "roomJoined",
+  ON_NEW_TASK = "onNewTask",
+  ON_EVALUATE = "onEvaluate",
+}

package/acp-seller/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "lib": ["ES2022"]
+  },
+  "include": ["bin/**/*.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "scripts", "seller"]
+}

package/bin/spendos.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { execSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, '..');
+
+// If setup.sh exists, run the interactive setup
+const setupScript = resolve(root, 'setup.sh');
+if (existsSync(setupScript)) {
+  const child = spawn('bash', [setupScript, ...process.argv.slice(2)], {
+    cwd: root,
+    stdio: 'inherit',
+    env: { ...process.env },
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+} else {
+  console.error('SpendOS setup.sh not found. Run from the spendos directory.');
+  process.exit(1);
+}

package/contracts/SpendOSAudit.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+contract SpendOSAudit {
+    event SpendEvent(
+        address indexed agent,
+        bytes32 indexed delegationHash,
+        string action,
+        string details,
+        uint256 amount,
+        uint256 timestamp
+    );
+
+    function log(
+        bytes32 delegationHash,
+        string calldata action,
+        string calldata details,
+        uint256 amount
+    ) external {
+        emit SpendEvent(
+            msg.sender,
+            delegationHash,
+            action,
+            details,
+            amount,
+            block.timestamp
+        );
+    }
+}

package/dist/mcp-server.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+// src/mcp-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var SPENDOS_URL = process.env.SPENDOS_URL ?? "http://localhost:3030";
+var server = new Server(
+  { name: "spendos", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "summarize_url",
+      description: "Summarize a URL into a concise brief. Costs $0.01 via x402. Powered by Venice AI (wallet-authenticated, decentralized inference).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "The URL to summarize" }
+        },
+        required: ["url"]
+      }
+    },
+    {
+      name: "generate_image",
+      description: "Generate an image from a text prompt. Costs $0.05 via x402. Powered by Venice AI.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          prompt: { type: "string", description: "Text description of the image to generate" }
+        },
+        required: ["prompt"]
+      }
+    },
+    {
+      name: "check_pnl",
+      description: "Check the SpendOS agent P&L (earnings, spending, profit margin).",
+      inputSchema: { type: "object", properties: {} }
+    },
+    {
+      name: "request_delegation",
+      description: "Request a spending delegation from SpendOS governance. Must be approved by the wallet owner before the agent can sign transactions.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          reason: { type: "string", description: "Why the agent needs spending permission" },
+          chains: { type: "array", items: { type: "string" }, description: "CAIP-2 chain IDs (e.g. eip155:8453)" },
+          totalBudget: { type: "string", description: "Maximum total spend in USD" },
+          expiresInMinutes: { type: "number", description: "How many minutes until the delegation expires" }
+        },
+        required: ["reason"]
+      }
+    }
+  ]
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  switch (name) {
+    case "summarize_url": {
+      const res = await fetch(`${SPENDOS_URL}/api/summarize`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ url: args?.url })
+      });
+      if (res.status === 402) {
+        return { content: [{ type: "text", text: "Payment required: $0.01 via x402. This endpoint is gated by the x402 payment protocol." }] };
+      }
+      const data = await res.json();
+      return {
+        content: [{
+          type: "text",
+          text: `Summary: ${data.summary}
+
+Cost: earned $${data.cost?.earned}, inference $${data.cost?.inference}, profit $${data.cost?.profit}`
+        }]
+      };
+    }
+    case "generate_image": {
+      const res = await fetch(`${SPENDOS_URL}/api/generate-image`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ prompt: args?.prompt })
+      });
+      if (res.status === 402) {
+        return { content: [{ type: "text", text: "Payment required: $0.05 via x402." }] };
+      }
+      const data = await res.json();
+      const imageUrl = data.images?.[0]?.url ?? data.images?.[0]?.b64_json ? "[base64 image]" : "no image";
+      return {
+        content: [{ type: "text", text: `Image generated: ${imageUrl}
+Cost: earned $0.05, inference $0.01, profit $0.04` }]
+      };
+    }
+    case "check_pnl": {
+      const res = await fetch(`${SPENDOS_URL}/api/pnl`);
+      const pnl = await res.json();
+      const margin = pnl.totalEarned > 0 ? (pnl.profit / pnl.totalEarned * 100).toFixed(0) : "n/a";
+      return {
+        content: [{
+          type: "text",
+          text: `Agent P&L:
+  Earned: $${pnl.totalEarned.toFixed(3)}
+  Spent: $${pnl.totalSpent.toFixed(4)}
+  Profit: $${pnl.profit.toFixed(4)}
+  Queries: ${pnl.queryCount}
+  Margin: ${margin}%`
+        }]
+      };
+    }
+    case "request_delegation": {
+      const expiresAt = new Date(Date.now() + (Number(args?.expiresInMinutes) || 30) * 6e4).toISOString();
+      const res = await fetch(`${SPENDOS_URL}/api/delegate`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          agentAddress: "0x0000000000000000000000000000000000000000",
+          // MCP agent
+          reason: args?.reason ?? "MCP tool request",
+          chains: args?.chains ?? ["eip155:8453"],
+          operations: ["sign_tx"],
+          maxAmountPerAction: args?.totalBudget ?? "1.00",
+          totalBudget: args?.totalBudget ?? "1.00",
+          expiresAt
+        })
+      });
+      const d = await res.json();
+      return {
+        content: [{
+          type: "text",
+          text: `Delegation requested:
+  ID: ${d.id}
+  Status: ${d.status}
+  Risk: ${d.aiInterpretation?.riskLevel ?? "unknown"}
+  Warnings: ${d.aiInterpretation?.warnings?.join("; ") ?? "none"}
+
+Awaiting wallet owner approval in SpendOS dashboard.`
+        }]
+      };
+    }
+    default:
+      return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[SpendOS MCP] Server started on stdio");
+}
+main().catch(console.error);

package/jobs/translate.json

@@ -0,0 +1,7 @@
+{
+  "name": "translate",
+  "price": "$0.02",
+  "prompt": "Translate the following text to {{language}}. Return only the translation, no explanation.\n\nText: {{text}}",
+  "inputs": ["text", "language"],
+  "description": "Translate text to any language"
+}

package/jobs/tweet-gen.json

@@ -0,0 +1,7 @@
+{
+  "name": "tweet-gen",
+  "price": "$0.01",
+  "prompt": "Write a banger crypto twitter post about: {{topic}}. Make it punchy, authentic, no corporate speak. Use line breaks for readability. Include relevant hashtags. Max 280 chars per tweet but can be a thread of 2-3 tweets if needed.",
+  "inputs": ["topic"],
+  "description": "Generate viral crypto tweets from a topic"
+}

package/openclaw.json

@@ -0,0 +1,41 @@
+{
+  "name": "spendos-agent",
+  "description": "SpendOS autonomous agent with governed spending",
+  "mcpServers": {
+    "moonpay": {
+      "command": "npx",
+      "args": ["@moonpay/cli", "mcp"],
+      "toolFilter": {
+        "allow": [
+          "token_search",
+          "token_retrieve",
+          "token_quote",
+          "token_balance_list",
+          "token_check",
+          "token_trending_list",
+          "token_holder_list",
+          "chain_list",
+          "chain_retrieve",
+          "wallet_list",
+          "wallet_retrieve"
+        ]
+      }
+    },
+    "zerion": {
+      "url": "https://developers.zerion.io/mcp",
+      "transport": "streamable-http"
+    },
+    "spendos": {
+      "command": "npx",
+      "args": ["tsx", "src/mcp-server.ts"],
+      "env": {
+        "SPENDOS_URL": "http://localhost:3030"
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "workspace": "."
+    }
+  }
+}