spendos 0.1.0

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

@@ -0,0 +1,1041 @@
+#!/usr/bin/env npx tsx
+// =============================================================================
+// Seller runtime — main entrypoint.
+//
+// Usage:
+//   npx tsx src/seller/runtime/seller.ts
+//   (or)  acp serve start
+// =============================================================================
+
+import { pathToFileURL } from "url";
+import { connectAcpSocket } from "./acpSocket.js";
+import { acceptOrRejectJob, requestPayment, deliverJob } from "./sellerApi.js";
+import {
+  loadOffering,
+  listOfferings,
+  logOfferingsStatus,
+  assertCanonicalOfferingsOrThrow,
+} from "./offerings.js";
+import { AcpJobPhase, MemoType, type AcpJobEventData } from "./types.js";
+import {
+  verifyPaymentProof,
+  verifyPaymentOnChain,
+} from "./paymentVerification.js";
+import type { ExecuteJobResult } from "./offeringTypes.js";
+import { getMyAgentInfo } from "../../lib/wallet.js";
+import {
+  checkForExistingProcess,
+  writePidToConfig,
+  removePidFromConfig,
+  sanitizeAgentName,
+} from "../../lib/config.js";
+import { validateStartupOrExit } from "./startup.js";
+
+function setupCleanupHandlers(): void {
+  const cleanup = () => {
+    removePidFromConfig();
+  };
+
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("uncaughtException", (err) => {
+    console.error("[seller] Uncaught exception:", err);
+    cleanup();
+    process.exit(1);
+  });
+  process.on("unhandledRejection", (reason, promise) => {
+    console.error(
+      "[seller] Unhandled rejection at:",
+      promise,
+      "reason:",
+      reason,
+    );
+    cleanup();
+    process.exit(1);
+  });
+}
+
+// -- Config --
+
+const ACP_URL = process.env.ACP_SOCKET_URL || "https://acpx.virtuals.io";
+const JOB_TIMEOUT_MS = Number(process.env.ACP_JOB_TIMEOUT_MS) || 180_000; // 3 min default
+const MAX_CONCURRENT_JOBS = Number(process.env.ACP_MAX_CONCURRENT_JOBS) || 3;
+const MAX_CONCURRENT_REQUESTS =
+  Number(process.env.ACP_MAX_CONCURRENT_REQUESTS) || 10;
+const VERIFY_PAYMENT_ONCHAIN =
+  process.env.ACP_VERIFY_PAYMENT_ONCHAIN?.toLowerCase() === "true";
+let agentDirName: string = "";
+let sellerWalletAddressLower = "";
+const availableOfferings = new Set<string>();
+const seenJobPhaseEvents = new Map<string, number>();
+const JOB_PHASE_EVENT_TTL_MS = 6 * 60 * 60 * 1000;
+const MAX_TRACKED_JOB_PHASE_EVENTS = 10_000;
+
+// Concurrency guard: prevent overlapping processing of the same jobId
+const inFlightJobs = new Set<number>();
+
+// -- Timeout helper --
+
+class JobTimeoutError extends Error {
+  constructor(jobId: number, offeringName: string, timeoutMs: number) {
+    super(
+      `Job ${jobId} timed out after ${timeoutMs}ms executing offering "${offeringName}"`,
+    );
+    this.name = "JobTimeoutError";
+  }
+}
+
+function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  jobId: number,
+  offeringName: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new JobTimeoutError(jobId, offeringName, timeoutMs)),
+      timeoutMs,
+    );
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+// -- Bounded concurrency --
+
+class JobSemaphore {
+  private running = 0;
+  private waitQueue: Array<() => void> = [];
+
+  constructor(private readonly maxConcurrent: number) {}
+
+  async acquire(jobId: number): Promise<void> {
+    if (this.running < this.maxConcurrent) {
+      this.running++;
+      return;
+    }
+    console.log(
+      `[seller] Job ${jobId} queued — waiting for a concurrency slot ` +
+        `(${this.running}/${this.maxConcurrent} active)`,
+    );
+    return new Promise<void>((resolve) => {
+      this.waitQueue.push(() => {
+        this.running++;
+        resolve();
+      });
+    });
+  }
+
+  release(): void {
+    this.running--;
+    const next = this.waitQueue.shift();
+    if (next) next();
+  }
+
+  get activeCount(): number {
+    return this.running;
+  }
+
+  get waitingCount(): number {
+    return this.waitQueue.length;
+  }
+}
+
+const jobSemaphore = new JobSemaphore(MAX_CONCURRENT_JOBS);
+// Separate, higher-limit semaphore for REQUEST phase (accept/reject).
+// REQUEST is fast (single API call) but still needs a bound to prevent
+// unbounded concurrency under burst conditions (e.g. socket reconnect replay).
+const requestSemaphore = new JobSemaphore(MAX_CONCURRENT_REQUESTS);
+
+// -- Job handling --
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function parseMemoJson(content: string): Record<string, unknown> | undefined {
+  try {
+    const parsed = JSON.parse(content);
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function pluckOfferingName(
+  payload: Record<string, unknown>,
+): string | undefined {
+  const candidates = [
+    payload.name,
+    payload.offering,
+    payload.offeringName,
+    payload.service,
+    payload.serviceName,
+  ];
+
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      return candidate.trim();
+    }
+  }
+
+  return undefined;
+}
+
+function pluckRequirements(
+  payload: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  const requirementKeys = [
+    "requirement",
+    "requirements",
+    "serviceRequirements",
+    "input",
+    "data",
+    "params",
+    "payload",
+    "request",
+  ];
+
+  for (const key of requirementKeys) {
+    const candidate = payload[key];
+    if (isRecord(candidate)) {
+      return normalizeRequirementsShape(candidate, payload);
+    }
+  }
+
+  if (hasWalletKey(payload)) {
+    return normalizeRequirementsShape(payload, payload);
+  }
+
+  return undefined;
+}
+
+function isNonEmptyWalletValue(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function hasWalletKey(source: Record<string, unknown>): boolean {
+  return (
+    typeof source.wallet === "string" ||
+    typeof source.address === "string" ||
+    typeof source.walletAddress === "string"
+  );
+}
+
+function pickWalletValue(source: Record<string, unknown>): string | undefined {
+  const candidates = [source.walletAddress, source.wallet, source.address];
+  for (const candidate of candidates) {
+    if (isNonEmptyWalletValue(candidate)) {
+      return candidate.trim();
+    }
+  }
+  return undefined;
+}
+
+function normalizeRequirementsShape(
+  requirement: Record<string, unknown>,
+  payload: Record<string, unknown>,
+): Record<string, unknown> {
+  if (Array.isArray(requirement)) {
+    return requirement;
+  }
+
+  const normalized: Record<string, unknown> = { ...requirement };
+  const hoistedWallet = pickWalletValue(normalized);
+  if (hoistedWallet) {
+    normalized.walletAddress = hoistedWallet;
+    delete normalized.wallet;
+    delete normalized.address;
+  }
+  return normalized;
+}
+
+function getMemoPayloads(
+  data: AcpJobEventData,
+): Array<Record<string, unknown>> {
+  const orderedMemos = [
+    ...data.memos.filter((m) => m.nextPhase === AcpJobPhase.NEGOTIATION),
+    ...data.memos.filter((m) => m.nextPhase !== AcpJobPhase.NEGOTIATION),
+  ];
+
+  const payloads = orderedMemos
+    .map((memo) => parseMemoJson(memo.content))
+    .filter((payload): payload is Record<string, unknown> => Boolean(payload));
+
+  if (isRecord(data.context)) {
+    payloads.push(data.context);
+  }
+
+  return payloads;
+}
+
+function resolveOfferingName(data: AcpJobEventData): string | undefined {
+  for (const payload of getMemoPayloads(data)) {
+    const offeringName = pluckOfferingName(payload);
+    if (offeringName) {
+      return offeringName;
+    }
+  }
+
+  return undefined;
+}
+
+function resolveServiceRequirements(
+  data: AcpJobEventData,
+): Record<string, any> {
+  for (const payload of getMemoPayloads(data)) {
+    const requirement = pluckRequirements(payload);
+    if (requirement) {
+      return requirement;
+    }
+  }
+
+  return {};
+}
+
+function shouldDeferWalletValidation(
+  _offeringName: string,
+  _reason: string | undefined,
+): boolean {
+  // Reject missing/invalid wallet at REQUEST so users are not charged for
+  // guaranteed-failing jobs in TRANSACTION.
+  return false;
+}
+
+function isGuardianWalletOffering(offeringName: string): boolean {
+  return (
+    /^x402janus_(scan(_quick|_standard|_deep)?|forensic_intelligence|deep_intelligence|approvals|revoke(_batch)?)$/.test(
+      offeringName,
+    ) || /^guardian_scan_(quick|standard|deep)$/.test(offeringName)
+  );
+}
+
+function hasWalletField(requirements: Record<string, unknown>): boolean {
+  return (
+    isNonEmptyWalletValue(requirements.walletAddress) ||
+    isNonEmptyWalletValue(requirements.wallet) ||
+    isNonEmptyWalletValue(requirements.address)
+  );
+}
+
+function withClientWalletFallback(
+  offeringName: string | undefined,
+  requirements: Record<string, unknown>,
+  data: AcpJobEventData,
+  phase: "REQUEST" | "TRANSACTION",
+  jobId: number,
+): Record<string, unknown> {
+  if (
+    !offeringName ||
+    !isGuardianWalletOffering(offeringName) ||
+    hasWalletField(requirements)
+  ) {
+    return requirements;
+  }
+
+  const clientAddress =
+    typeof data.clientAddress === "string" ? data.clientAddress.trim() : "";
+  if (!/^0x[a-fA-F0-9]{40}$/.test(clientAddress)) {
+    return requirements;
+  }
+
+  console.log(
+    `[seller] Job ${jobId} using clientAddress as wallet fallback for "${offeringName}" in ${phase}`,
+  );
+  return {
+    ...requirements,
+    walletAddress: clientAddress,
+  };
+}
+
+function toValidationResult(
+  validationResult: boolean | { valid: boolean; reason?: string },
+): { valid: boolean; reason?: string } {
+  if (typeof validationResult === "boolean") {
+    return {
+      valid: validationResult,
+      reason: validationResult ? undefined : "Validation failed",
+    };
+  }
+
+  return validationResult;
+}
+
+function trackAndCheckDuplicate(jobId: number, phase: AcpJobPhase): boolean {
+  const now = Date.now();
+  const eventKey = `${jobId}:${phase}`;
+
+  // Purge expired entries (Map is insertion-ordered so oldest are first)
+  for (const [key, seenAt] of seenJobPhaseEvents) {
+    if (now - seenAt > JOB_PHASE_EVENT_TTL_MS) {
+      seenJobPhaseEvents.delete(key);
+    } else {
+      break;
+    }
+  }
+
+  if (seenJobPhaseEvents.has(eventKey)) {
+    return true;
+  }
+
+  seenJobPhaseEvents.set(eventKey, now);
+
+  // Hard cap: batch-evict oldest 10% when threshold exceeded to avoid
+  // unbounded growth if TTL purge alone can't keep up with throughput.
+  if (seenJobPhaseEvents.size > MAX_TRACKED_JOB_PHASE_EVENTS) {
+    const evictCount = Math.max(
+      1,
+      Math.floor(MAX_TRACKED_JOB_PHASE_EVENTS * 0.1),
+    );
+    const iter = seenJobPhaseEvents.keys();
+    for (let i = 0; i < evictCount; i++) {
+      const next = iter.next();
+      if (next.done) break;
+      seenJobPhaseEvents.delete(next.value);
+    }
+  }
+
+  return false;
+}
+
+function getWalletFromRequirements(
+  requirements: Record<string, unknown>,
+): string {
+  return pickWalletValue(requirements) ?? "";
+}
+
+function buildValidationErrorDeliverable(
+  offeringName: string,
+  reason: string,
+  requirements: Record<string, unknown>,
+): ExecuteJobResult["deliverable"] {
+  return {
+    type: "guardian_scan_error",
+    value: {
+      success: false,
+      error: "Invalid scan requirements",
+      reason,
+      offering: offeringName,
+      wallet: getWalletFromRequirements(requirements),
+    },
+  };
+}
+
+function buildExecutionErrorDeliverable(
+  offeringName: string,
+  err: unknown,
+  requirements: Record<string, unknown>,
+): ExecuteJobResult["deliverable"] {
+  const reason =
+    err instanceof Error && err.message ? err.message : "Internal error";
+
+  return {
+    type: isGuardianWalletOffering(offeringName)
+      ? "guardian_scan_error"
+      : "execution_error",
+    value: {
+      success: false,
+      error: "Job execution failed",
+      reason,
+      offering: offeringName,
+      wallet: getWalletFromRequirements(requirements),
+    },
+  };
+}
+
+async function handleNewTask(data: AcpJobEventData): Promise<void> {
+  const jobId = data.id;
+
+  if (
+    sellerWalletAddressLower &&
+    typeof data.providerAddress === "string" &&
+    data.providerAddress.toLowerCase() !== sellerWalletAddressLower
+  ) {
+    console.log(
+      `[seller] Ignoring job ${jobId}: provider mismatch (job=${data.providerAddress}, self=${sellerWalletAddressLower})`,
+    );
+    return;
+  }
+
+  if (trackAndCheckDuplicate(jobId, data.phase)) {
+    console.log(
+      `[seller] Duplicate event ignored for job ${jobId} phase=${AcpJobPhase[data.phase] ?? data.phase}`,
+    );
+    return;
+  }
+
+  if (inFlightJobs.has(jobId)) {
+    console.log(
+      `[seller] Job ${jobId} already in-flight — skipping concurrent execution`,
+    );
+    return;
+  }
+  inFlightJobs.add(jobId);
+
+  console.log(`\n${"=".repeat(60)}`);
+  console.log(
+    `[seller] New task  jobId=${jobId}  phase=${AcpJobPhase[data.phase] ?? data.phase}`,
+  );
+  console.log(`         client=${data.clientAddress}  price=${data.price}`);
+  console.log(`         context=${JSON.stringify(data.context)}`);
+  console.log(`${"=".repeat(60)}`);
+
+  // Step 1: Accept / reject
+  if (data.phase === AcpJobPhase.REQUEST) {
+    const requestStartMs = Date.now();
+
+    if (!data.memoToSign) {
+      console.log(
+        `[seller] Job ${jobId} REQUEST phase — no memoToSign, skipping`,
+      );
+      return;
+    }
+
+    const negotiationMemo = data.memos.find(
+      (m) => m.id == Number(data.memoToSign),
+    );
+
+    if (!negotiationMemo) {
+      console.log(
+        `[seller] Job ${jobId} REQUEST phase — memo ${data.memoToSign} not found in ${data.memos.length} memos`,
+      );
+      return;
+    }
+
+    if (negotiationMemo.nextPhase !== AcpJobPhase.NEGOTIATION) {
+      console.log(
+        `[seller] Job ${jobId} REQUEST phase — memo nextPhase=${AcpJobPhase[negotiationMemo.nextPhase] ?? negotiationMemo.nextPhase}, expected NEGOTIATION`,
+      );
+      return;
+    }
+
+    const offeringName = resolveOfferingName(data);
+    const requirements = withClientWalletFallback(
+      offeringName,
+      resolveServiceRequirements(data),
+      data,
+      "REQUEST",
+      jobId,
+    );
+
+    console.log(
+      `[seller] Job ${jobId} — offering="${offeringName}" agentDir="${agentDirName}" requirementKeys=${JSON.stringify(Object.keys(requirements))}`,
+    );
+
+    if (!offeringName) {
+      await acceptOrRejectJob(jobId, {
+        accept: false,
+        reason: "Invalid offering name",
+      });
+      return;
+    }
+
+    if (!availableOfferings.has(offeringName)) {
+      await acceptOrRejectJob(jobId, {
+        accept: false,
+        reason: "Offering unavailable",
+      });
+      return;
+    }
+
+    let accepted = false;
+
+    try {
+      const { config, handlers } = await loadOffering(
+        offeringName,
+        agentDirName,
+      );
+
+      if (handlers.validateRequirements) {
+        const validationResult = handlers.validateRequirements(requirements);
+        const parsedResult = toValidationResult(validationResult);
+
+        if (!parsedResult.valid) {
+          const rejectionReason = parsedResult.reason || "Validation failed";
+          const shouldDeferValidation = shouldDeferWalletValidation(
+            offeringName,
+            rejectionReason,
+          );
+
+          if (shouldDeferValidation) {
+            console.log(
+              `[seller] Deferring wallet validation for job ${jobId} offering="${offeringName}" until TRANSACTION phase`,
+            );
+          } else {
+            console.log(
+              `[seller] Validation failed for offering "${offeringName}" — rejecting: ${rejectionReason}`,
+            );
+            await acceptOrRejectJob(jobId, {
+              accept: false,
+              reason: rejectionReason,
+            });
+            return;
+          }
+        }
+      }
+
+      await acceptOrRejectJob(jobId, {
+        accept: true,
+        reason: "Job accepted",
+      });
+      accepted = true;
+      console.log(
+        `[seller] Job ${jobId} — accepted in ${Date.now() - requestStartMs}ms`,
+      );
+
+      const funds =
+        config.requiredFunds && handlers.requestAdditionalFunds
+          ? handlers.requestAdditionalFunds(requirements)
+          : undefined;
+
+      const paymentReason = handlers.requestPayment
+        ? handlers.requestPayment(requirements)
+        : (funds?.content ?? "Request accepted");
+
+      await requestPayment(jobId, {
+        content: paymentReason,
+        payableDetail: funds
+          ? {
+              amount: funds.amount,
+              tokenAddress: funds.tokenAddress,
+              recipient: funds.recipient,
+            }
+          : undefined,
+      });
+    } catch (err) {
+      console.error(`[seller] Error processing job ${jobId}:`, err);
+
+      if (!accepted) {
+        await acceptOrRejectJob(jobId, {
+          accept: false,
+          reason: "Internal error",
+        }).catch((rejectErr) => {
+          console.log(
+            `[seller] Failed to reject job ${jobId} after processing error:`,
+            rejectErr,
+          );
+        });
+      } else {
+        console.log(
+          `[seller] Job ${jobId} already accepted; skipping reject after processing error.`,
+        );
+      }
+    }
+  }
+
+  // Handle TRANSACTION (deliver)
+  if (data.phase === AcpJobPhase.TRANSACTION) {
+    const offeringName = resolveOfferingName(data);
+    const requirements = withClientWalletFallback(
+      offeringName,
+      resolveServiceRequirements(data),
+      data,
+      "TRANSACTION",
+      jobId,
+    );
+    console.log(
+      `[seller] Job ${jobId} TRANSACTION wallet resolved: ${pickWalletValue(requirements) ?? "NONE"}`,
+    );
+
+    // C-01 fix: Verify payment proof exists before executing.
+    // The TRANSACTION phase should only arrive after the client has paid,
+    // but we must not trust the ACP platform's phase transition blindly.
+    const paymentCheck = verifyPaymentProof(data.memos);
+    if (!paymentCheck.verified) {
+      console.error(
+        `[seller] Job ${jobId} — ${paymentCheck.reason} Refusing to execute.`,
+      );
+      await deliverJob(jobId, {
+        deliverable: {
+          type:
+            offeringName && isGuardianWalletOffering(offeringName)
+              ? "guardian_scan_error"
+              : "execution_error",
+          value: {
+            success: false,
+            error: "Payment verification failed",
+            reason: paymentCheck.reason ?? "Missing or invalid payment proof",
+            jobId,
+          },
+        },
+      }).catch((err) => {
+        console.error(
+          `[seller] Failed to deliver payment error for job ${jobId}:`,
+          err,
+        );
+      });
+      return;
+    }
+
+    const paymentContent = paymentCheck.memo!.content.trim();
+    console.log(
+      `[seller] Job ${jobId} — payment proof format verified ` +
+        `(type=${MemoType[paymentCheck.memo!.memoType]}, content=${paymentContent.slice(0, 20)}...)`,
+    );
+
+    // C-01 Phase 2: On-chain payment verification.
+    // Confirms the tx hash corresponds to a real, successful USDC transfer
+    // on Base with the correct amount and recipient.
+    const onChainFailureDeliverableType =
+      offeringName && isGuardianWalletOffering(offeringName)
+        ? "guardian_scan_error"
+        : "execution_error";
+
+    const deliverOnChainVerificationError = async (reason: string) => {
+      await deliverJob(jobId, {
+        deliverable: {
+          type: onChainFailureDeliverableType,
+          value: {
+            success: false,
+            error: "On-chain payment verification failed",
+            reason,
+            jobId,
+          },
+        },
+      }).catch((err) => {
+        console.error(
+          `[seller] Failed to deliver on-chain payment error for job ${jobId}:`,
+          err,
+        );
+      });
+    };
+
+    if (VERIFY_PAYMENT_ONCHAIN) {
+      try {
+        // Convert price (USDC with 6 decimals) to token units.
+        // data.price is a number like 0.5 meaning 0.5 USDC.
+        const priceInTokenUnits =
+          typeof data.price === "number" && data.price > 0
+            ? BigInt(Math.round(data.price * 1e6))
+            : undefined;
+
+        console.log(
+          `[seller] Job ${jobId} — verifying payment on-chain ` +
+            `(recipient=${sellerWalletAddressLower || "any"}, minAmount=${priceInTokenUnits ?? "any"})`,
+        );
+
+        const onChainResult = await verifyPaymentOnChain(
+          paymentContent as `0x${string}`,
+          {
+            expectedRecipient: sellerWalletAddressLower || undefined,
+            expectedMinAmount: priceInTokenUnits,
+          },
+        );
+
+        if (!onChainResult.verified) {
+          console.error(
+            `[seller] Job ${jobId} — on-chain payment verification FAILED: ${onChainResult.reason}`,
+          );
+          await deliverOnChainVerificationError(
+            onChainResult.reason ??
+              "On-chain payment verification returned verified=false",
+          );
+          return;
+        }
+
+        console.log(
+          `[seller] Job ${jobId} — on-chain payment VERIFIED ` +
+            `(from=${onChainResult.from}, to=${onChainResult.to}, amount=${onChainResult.amount}, block=${onChainResult.blockNumber})`,
+        );
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(
+          `[seller] Job ${jobId} — on-chain verification error: ${message}`,
+        );
+        await deliverOnChainVerificationError(
+          `On-chain verification error: ${message}`,
+        );
+        return;
+      }
+    } else {
+      console.log(
+        `[seller] Job ${jobId} — on-chain payment verification SKIPPED ` +
+          `(set ACP_VERIFY_PAYMENT_ONCHAIN=true to enable)`,
+      );
+    }
+
+    const sigilxPaymentMetadata = {
+      acpJobId: jobId,
+      buyerWallet: data.clientAddress,
+      transferId: paymentContent,
+    };
+    const enrichedRequirements = {
+      ...requirements,
+      __sigilxPayment: sigilxPaymentMetadata,
+    };
+
+    if (offeringName) {
+      if (!availableOfferings.has(offeringName)) {
+        console.error(
+          `[seller] Job ${jobId} in TRANSACTION references unavailable offering "${offeringName}"`,
+        );
+        await deliverJob(jobId, {
+          deliverable: {
+            type: isGuardianWalletOffering(offeringName)
+              ? "guardian_scan_error"
+              : "execution_error",
+            value: {
+              success: false,
+              error: `Offering "${offeringName}" is not available`,
+              reason: "OFFERING_UNAVAILABLE",
+              jobId,
+            },
+          },
+        }).catch((err) => {
+          console.error(
+            `[seller] Failed to deliver unavailable-offering error for job ${jobId}:`,
+            err,
+          );
+        });
+        return;
+      }
+
+      let executionResult: ExecuteJobResult | null = null;
+      try {
+        const { handlers } = await loadOffering(offeringName, agentDirName);
+
+        if (handlers.validateRequirements) {
+          const validationResult =
+            handlers.validateRequirements(enrichedRequirements);
+          const parsedResult = toValidationResult(validationResult);
+
+          if (!parsedResult.valid) {
+            const rejectionReason = parsedResult.reason || "Validation failed";
+            console.log(
+              `[seller] Job ${jobId} failed TRANSACTION validation for "${offeringName}": ${rejectionReason}`,
+            );
+            await deliverJob(jobId, {
+              deliverable: buildValidationErrorDeliverable(
+                offeringName,
+                rejectionReason,
+                enrichedRequirements,
+              ),
+            });
+            return;
+          }
+        }
+
+        console.log(
+          `[seller] Executing offering "${offeringName}" for job ${jobId} (TRANSACTION phase, timeout=${JOB_TIMEOUT_MS}ms)...`,
+        );
+        executionResult = await withTimeout(
+          handlers.executeJob(enrichedRequirements),
+          JOB_TIMEOUT_MS,
+          jobId,
+          offeringName,
+        );
+
+        await deliverJob(jobId, {
+          deliverable: executionResult.deliverable,
+          payableDetail: executionResult.payableDetail,
+        });
+        console.log(`[seller] Job ${jobId} — delivered.`);
+      } catch (err) {
+        console.error(`[seller] Error delivering job ${jobId}:`, err);
+        if (!executionResult) {
+          await deliverJob(jobId, {
+            deliverable: buildExecutionErrorDeliverable(
+              offeringName,
+              err,
+              enrichedRequirements,
+            ),
+          }).catch((deliverErr) => {
+            console.log(
+              `[seller] Failed to deliver execution error for job ${jobId}:`,
+              deliverErr,
+            );
+          });
+        } else {
+          console.log(
+            `[seller] Delivery failed after successful execution for job ${jobId}; ` +
+              "not sending synthetic execution error deliverable.",
+          );
+        }
+      }
+    } else {
+      console.error(
+        `[seller] Job ${jobId} in TRANSACTION but no offering resolved`,
+      );
+      await deliverJob(jobId, {
+        deliverable: {
+          type: "execution_error",
+          value: {
+            success: false,
+            error: "Could not resolve offering name from job memos",
+            reason: "OFFERING_UNRESOLVED",
+            jobId,
+          },
+        },
+      }).catch((err) => {
+        console.error(
+          `[seller] Failed to deliver unresolved-offering error for job ${jobId}:`,
+          err,
+        );
+      });
+    }
+    return;
+  }
+
+  console.log(
+    `[seller] Job ${jobId} in phase ${AcpJobPhase[data.phase] ?? data.phase} — no action needed`,
+  );
+}
+
+// -- Main --
+
+async function main() {
+  checkForExistingProcess();
+
+  writePidToConfig(process.pid);
+
+  setupCleanupHandlers();
+
+  let walletAddress: string;
+  try {
+    const agentData = await getMyAgentInfo();
+    walletAddress = agentData.walletAddress;
+    sellerWalletAddressLower = walletAddress.toLowerCase();
+    agentDirName = sanitizeAgentName(agentData.name);
+    if (agentDirName === "") {
+      console.error(
+        `[seller] sanitizeAgentName produced invalid directory name "${agentDirName}" for agent name "${agentData.name}". Cannot resolve offering paths safely.`,
+      );
+      process.exit(1);
+    }
+    console.log(`[seller] Agent: ${agentData.name} (dir: ${agentDirName})`);
+  } catch (err) {
+    console.error("[seller] Failed to resolve agent info:", err);
+    process.exit(1);
+  }
+
+  // Preflight: validate env vars (GUARDIAN_INTERNAL_API_TOKEN, etc.) and offerings
+  validateStartupOrExit(agentDirName);
+
+  const offerings = listOfferings(agentDirName);
+  assertCanonicalOfferingsOrThrow(agentDirName, offerings);
+
+  availableOfferings.clear();
+  for (const offering of offerings) {
+    availableOfferings.add(offering);
+  }
+  logOfferingsStatus(agentDirName, offerings);
+
+  // Pre-warm offering handlers: cache the dynamic import() so the first
+  // incoming job doesn't pay the module-transpile + load penalty.
+  const warmStartMs = Date.now();
+  await Promise.all(
+    offerings.map(async (name) => {
+      try {
+        await loadOffering(name, agentDirName);
+      } catch (err) {
+        console.warn(`[seller] Failed to pre-warm offering "${name}":`, err);
+      }
+    }),
+  );
+  console.log(
+    `[seller] Pre-warmed ${offerings.length} offering handlers in ${Date.now() - warmStartMs}ms`,
+  );
+
+  console.log(
+    `[seller] Concurrency: requests=${MAX_CONCURRENT_REQUESTS}, jobs=${MAX_CONCURRENT_JOBS}, timeout=${JOB_TIMEOUT_MS}ms per job`,
+  );
+
+  connectAcpSocket({
+    acpUrl: ACP_URL,
+    walletAddress,
+    callbacks: {
+      onNewTask: (data) => {
+        if (data.phase === AcpJobPhase.REQUEST) {
+          // REQUEST phase (accept/reject + payment request) uses its own
+          // lighter semaphore so it is never blocked behind long-running
+          // TRANSACTION executions that would push it past the ACP TTL.
+          requestSemaphore
+            .acquire(data.id)
+            .then(() => handleNewTask(data))
+            .catch((err) =>
+              console.error(
+                "[seller] Unhandled error in handleNewTask (REQUEST):",
+                err,
+              ),
+            )
+            .finally(() => {
+              inFlightJobs.delete(data.id);
+              requestSemaphore.release();
+            });
+        } else {
+          // TRANSACTION phase: actual job execution, bounded concurrency.
+          jobSemaphore
+            .acquire(data.id)
+            .then(() => handleNewTask(data))
+            .catch((err) =>
+              console.error("[seller] Unhandled error in handleNewTask:", err),
+            )
+            .finally(() => {
+              inFlightJobs.delete(data.id);
+              jobSemaphore.release();
+            });
+        }
+      },
+      onEvaluate: (data) => {
+        console.log(
+          `[seller] onEvaluate received for job ${data.id} — no action (evaluation handled externally)`,
+        );
+      },
+    },
+  });
+
+  if (VERIFY_PAYMENT_ONCHAIN) {
+    console.log(
+      "[seller] On-chain payment verification ENABLED (ACP_VERIFY_PAYMENT_ONCHAIN=true)",
+    );
+  } else {
+    console.warn(
+      "[seller] WARNING: On-chain payment verification DISABLED. " +
+        "Set ACP_VERIFY_PAYMENT_ONCHAIN=true to verify payments on Base before executing jobs.",
+    );
+  }
+
+  console.log("[seller] Seller runtime is running. Waiting for jobs...\n");
+}
+
+export { JobTimeoutError };
+
+export const __testing = {
+  handleNewTask,
+  resolveOfferingName,
+  resolveServiceRequirements,
+  trackAndCheckDuplicate,
+  resetSeenEvents: () => seenJobPhaseEvents.clear(),
+  resetInFlightJobs: () => inFlightJobs.clear(),
+  getInFlightJobs: () => inFlightJobs,
+  setSellerWallet: (addr: string) => {
+    sellerWalletAddressLower = addr.toLowerCase();
+  },
+  setAgentDirName: (name: string) => {
+    agentDirName = name;
+  },
+  setAvailableOfferings: (names: string[]) => {
+    availableOfferings.clear();
+    for (const n of names) availableOfferings.add(n);
+  },
+  JOB_TIMEOUT_MS,
+  MAX_CONCURRENT_JOBS,
+  jobSemaphore,
+};
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((err) => {
+    console.error("[seller] Fatal error:", err);
+    process.exit(1);
+  });
+}