@elisym/cli 0.22.5 → 0.23.0

package/dist/index.js

@@ -2,8 +2,8 @@
 import { ReadableStream } from 'node:stream/web';
 import { readFileSync, existsSync, readdirSync, statSync, renameSync, chmodSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve, basename, extname, relative, sep } from 'node:path';
-import { SolanaPaymentStrategy, validateAgentName, RELAYS, ElisymIdentity, formatSol, formatAssetAmount, USDC_SOLANA_DEVNET, ElisymClient, POLICY_D_TAG_PREFIX, KIND_LONG_FORM_ARTICLE, jobRequestKind, DEFAULT_KIND_OFFSET, toDTag, DEFAULTS, createBlossomTransport, makeCensor, DEFAULT_REDACT_PATHS, POLICY_T_TAG, createSlidingWindowLimiter, getProtocolProgramId, getProtocolConfig, utf8ByteLength, LIMITS, readAcceptedTransports, calculateProtocolFee, decodeJobPayload, BoundedSet, KIND_JOB_FEEDBACK, NATIVE_SOL } from '@elisym/sdk';
-import { ElisymYamlSchema, resolveInHome, resolveInProject, createAgentDir, writeYamlInitial, writeExampleSkillTemplate, writeSecrets, listAgents, loadAgent, writeYaml, agentPaths, readMediaCache, loadPoliciesFromDir, ensureGitignoreHasIrohEntry, lookupCachedUrl, newCacheEntry, writeMediaCache } from '@elisym/sdk/agent-store';
+import { SolanaPaymentStrategy, validateAgentName, RELAYS, ElisymIdentity, formatSol, formatAssetAmount, USDC_SOLANA_DEVNET, signerFromSecretKeyBase58, ElisymClient, POLICY_D_TAG_PREFIX, KIND_LONG_FORM_ARTICLE, jobRequestKind, DEFAULT_KIND_OFFSET, toDTag, DEFAULTS, createBlossomTransport, generateSolanaWallet, getProtocolConfig, getProtocolProgramId, calculateProtocolFee, LIMITS, makeCensor, DEFAULT_REDACT_PATHS, POLICY_T_TAG, createSlidingWindowLimiter, utf8ByteLength, readAcceptedTransports, decodeJobPayload, BoundedSet, KIND_JOB_FEEDBACK, encodeSecretKeyBase58, NATIVE_SOL } from '@elisym/sdk';
+import { ElisymYamlSchema, resolveInHome, resolveInProject, createAgentDir, writeYamlInitial, writeExampleSkillTemplate, writeSecrets, listAgents, loadAgent, writeYaml, agentPaths, readMediaCache, loadPoliciesFromDir, ensureGitignoreHasIrohEntry, ensureGitignoreHasX402Entries, lookupCachedUrl, newCacheEntry, writeMediaCache } from '@elisym/sdk/agent-store';
 import { isAddress, createSolanaRpc, address } from '@solana/kit';
 import { generateSecretKey, getPublicKey, nip19, verifyEvent } from 'nostr-tools';
 import YAML from 'yaml';
@@ -14,10 +14,15 @@ import { createIrohTransport } from '@elisym/sdk/node';
 import { lookup } from 'node:dns/promises';
 import { Socket } from 'node:net';
 import pino from 'pino';
-import { readFile, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, writeFile, readFile, mkdtemp, rm, rename, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import pLimit from 'p-limit';
-import { parseSkillMd, validateSkillFrontmatter, resolveInsidePath, DEFAULT_SCRIPT_TIMEOUT_MS, DynamicScriptSkill as DynamicScriptSkill$1, StaticScriptSkill as StaticScriptSkill$1, StaticFileSkill as StaticFileSkill$1, ScriptSkill as ScriptSkill$1 } from '@elisym/sdk/skills';
+import { parseSkillMd, validateSkillFrontmatter, DEFAULT_X402_MAX_INPUT_BYTES, resolveInsidePath, DEFAULT_SCRIPT_TIMEOUT_MS, DynamicScriptSkill as DynamicScriptSkill$1, StaticScriptSkill as StaticScriptSkill$1, StaticFileSkill as StaticFileSkill$1, ScriptSkill as ScriptSkill$1 } from '@elisym/sdk/skills';
+import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
+import { ExactSvmScheme } from '@x402/svm';
+import { decodePaymentRequiredHeader } from '@x402/core/http';
+import chalk from 'chalk';
+import Decimal from 'decimal.js-light';
 import { fileURLToPath } from 'node:url';
 
 var __defProp = Object.defineProperty;
@@ -2066,6 +2071,43 @@ var MIME_BY_EXT = {
 function mimeFromPath(path) {
   return MIME_BY_EXT[extname(path).toLowerCase()] ?? "application/octet-stream";
 }
+
+// src/x402/errors.ts
+var X402PreflightError = class extends Error {
+  /**
+   * Optional customer-facing text. Preflight reasons split in two: input
+   * problems the CUSTOMER can act on (too large for a GET upstream) vs
+   * operator problems (empty float, negative margin) that must stay generic
+   * to avoid leaking billing state.
+   */
+  customerMessage;
+  constructor(message, customerMessage) {
+    super(message);
+    this.name = "X402PreflightError";
+    this.customerMessage = customerMessage;
+  }
+};
+var X402TransientError = class extends Error {
+  /**
+   * Final upstream HTTP status when the failure was a definitive response
+   * (402 refusal, 429, 5xx); absent for network-level failures. The driver
+   * keys the refund-and-retry decision on `402` here.
+   */
+  upstreamStatus;
+  constructor(message, upstreamStatus) {
+    super(message);
+    this.name = "X402TransientError";
+    this.upstreamStatus = upstreamStatus;
+  }
+};
+var X402PermanentError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "X402PermanentError";
+  }
+};
+
+// src/runtime.ts
 var payment = new SolanaPaymentStrategy();
 var LEDGER_GC_INTERVAL_MS = 60 * 60 * 1e3;
 var LEDGER_RETENTION_MS = 30 * 24 * 60 * 60 * 1e3;
@@ -2550,7 +2592,7 @@ var AgentRuntime = class {
       const log = this.callbacks.onLog ?? console.log;
       log(`[${job.jobId.slice(0, 8)}] Error: ${e.message}`);
       const currentStatus = this.ledger.getStatus(job.jobId);
-      const keepPaidForRecovery = (e instanceof AgentUnavailableError || e instanceof SeedFailedError || e instanceof PaymentTimeoutError) && currentStatus === "paid";
+      const keepPaidForRecovery = (e instanceof AgentUnavailableError || e instanceof SeedFailedError || e instanceof PaymentTimeoutError || e instanceof X402TransientError || e instanceof ExecutionBudgetExceededError && this.skills.route(job.tags)?.mode === "x402") && currentStatus === "paid";
       if (currentStatus !== "executed" && !keepPaidForRecovery) {
         this.ledger.markFailed(job.jobId);
       }
@@ -2589,6 +2631,37 @@ var AgentRuntime = class {
         return;
       }
     }
+    if (matched?.mode === "x402" && job.attachment !== void 0) {
+      const method = matched.x402?.method ?? "POST";
+      const maxInputBytes = matched.x402?.maxInputBytes ?? 0;
+      const attachmentOk = method === "POST" && job.attachment.mime.startsWith("text/") && job.attachment.size <= maxInputBytes;
+      if (!attachmentOk) {
+        log(
+          `[${job.jobId.slice(0, 8)}] Rejecting attachment on x402 skill (mime=${job.attachment.mime}, size=${job.attachment.size})`
+        );
+        await this.transport.sendFeedback(job, {
+          type: "error",
+          message: "This skill accepts inline text input only (or a text attachment within its size limit)."
+        }).catch(() => {
+        });
+        return;
+      }
+    }
+    if (matched?.preflight) {
+      try {
+        await matched.preflight(
+          { data: job.input, inputType: job.inputType, tags: job.tags, jobId: job.jobId },
+          this.skillCtx
+        );
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        log(`[${job.jobId.slice(0, 8)}] Preflight refused job: ${detail}`);
+        const customerMessage = err instanceof X402PreflightError && err.customerMessage !== void 0 ? err.customerMessage : AGENT_UNAVAILABLE_MESSAGE;
+        await this.transport.sendFeedback(job, { type: "error", message: customerMessage }).catch(() => {
+        });
+        return;
+      }
+    }
     if (job.attachment !== void 0 && resolveJobPrice(job.tags, this.skills) === 0) {
       log(`[${job.jobId.slice(0, 8)}] Rejecting file input on a free skill`);
       await this.transport.sendFeedback(job, { type: "error", message: "File inputs require a paid skill." }).catch(() => {
@@ -3332,6 +3405,25 @@ var AgentRuntime = class {
             throw err;
           }
         }
+        if (skill.preflight) {
+          try {
+            await skill.preflight(
+              {
+                data: entry.input,
+                inputType: entry.input_type,
+                tags: entry.tags,
+                jobId: entry.job_id
+              },
+              this.skillCtx
+            );
+          } catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            log(
+              `[${entry.job_id.slice(0, 8)}] Recovery: preflight refused (${detail}); waiting for next tick.`
+            );
+            return;
+          }
+        }
         this.ledger.incrementRetry(entry.job_id);
         if (skill.priceSubunits > 0 && !entry.net_amount) {
           if (entry.payment_request) {
@@ -3716,6 +3808,56 @@ var ScriptSkill = class {
   }
 };
 
+// src/skill/x402-skill.ts
+var X402Skill = class {
+  name;
+  description;
+  capabilities;
+  priceSubunits;
+  asset;
+  mode = "x402";
+  x402;
+  noInput;
+  image;
+  imageFile;
+  dir;
+  constructor(params) {
+    this.name = params.name;
+    this.description = params.description;
+    this.capabilities = params.capabilities;
+    this.priceSubunits = params.priceSubunits;
+    this.asset = params.asset;
+    this.x402 = params.x402;
+    this.noInput = params.noInput;
+    this.image = params.image;
+    this.imageFile = params.imageFile;
+    this.dir = params.dir;
+  }
+  requireDriver(ctx) {
+    if (ctx.x402Driver === void 0) {
+      throw new Error(
+        `Skill "${this.name}": x402 driver not wired into the skill context (internal error)`
+      );
+    }
+    return ctx.x402Driver;
+  }
+  asJob() {
+    return {
+      skillName: this.name,
+      params: this.x402,
+      priceSubunits: this.priceSubunits,
+      asset: this.asset
+    };
+  }
+  async preflight(input, ctx) {
+    await this.requireDriver(ctx).preflight(this.asJob(), input);
+  }
+  async execute(input, ctx) {
+    const result = await this.requireDriver(ctx).execute(this.asJob(), input, ctx.signal);
+    return { data: result.data, outputMime: result.outputMime, filePath: result.filePath };
+  }
+};
+
 // src/skill/loader.ts
 function buildCliSkill(parsed, entryPath, scriptEnv) {
   let safeImageFile = parsed.imageFile;
@@ -3803,6 +3945,26 @@ function buildCliSkill(parsed, entryPath, scriptEnv) {
       }) : new StaticScriptSkill(scriptParams);
       break;
     }
+    case "x402": {
+      if (parsed.x402 === void 0) {
+        throw new Error(
+          `SKILL.md "${parsed.name}": internal error - x402 config missing for mode 'x402'`
+        );
+      }
+      skill = new X402Skill({
+        name: parsed.name,
+        description: parsed.description,
+        capabilities: parsed.capabilities,
+        priceSubunits: Number(parsed.priceSubunits),
+        asset: parsed.asset,
+        x402: parsed.x402,
+        noInput: parsed.noInput === true,
+        image: parsed.image,
+        imageFile: safeImageFile,
+        dir: entryPath
+      });
+      break;
+    }
   }
   if (parsed.rateLimit) {
     skill.rateLimit = parsed.rateLimit;
@@ -3834,7 +3996,10 @@ function loadSkillsFromDir(skillsDir, options = {}) {
       const content = readFileSync(skillMdPath, "utf-8");
       const { frontmatter, systemPrompt } = parseSkillMd(content);
       const parsed = validateSkillFrontmatter(frontmatter, systemPrompt, {
-        allowFreeSkills: true
+        allowFreeSkills: true,
+        // The CLI runtime wires an x402 driver into the skill context, so
+        // x402 skills are executable here (SDK-only hosts reject them).
+        allowX402Skills: true
       });
       skills.push(buildCliSkill(parsed, entryPath, options.scriptEnv));
     } catch (e) {
@@ -4153,6 +4318,788 @@ function startWatchdog(deps) {
   };
 }
 
+// src/x402/constants.ts
+var X402_SOLANA_DEVNET_CAIP2 = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+var X402_SOLANA_DEVNET_V1 = "solana-devnet";
+var X402_GET_INPUT_MAX_ENCODED_BYTES = 2048;
+var X402_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+var X402_MAX_CHALLENGE_BYTES = 256 * 1024;
+var X402_PROBE_TTL_MS = 3e4;
+var X402_MAX_PAID_ATTEMPTS = 2;
+var X402_MAX_PAYMENT_SIGNATURES = 2 * X402_MAX_PAID_ATTEMPTS;
+var X402_FREE_RETRY_DELAYS_MS = [1e3, 3e3];
+var X402_REFUNDED_RETRIES = 1;
+var X402_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+function requirementAmount(requirement) {
+  const v1Amount = requirement.maxAmountRequired;
+  const raw = requirement.amount ?? v1Amount;
+  if (typeof raw !== "string" || !/^[0-9]+$/.test(raw)) {
+    return null;
+  }
+  return BigInt(raw);
+}
+function isAcceptableRequirement(requirement, rule) {
+  if (requirement.scheme !== "exact") {
+    return false;
+  }
+  const network = requirement.network;
+  if (network !== X402_SOLANA_DEVNET_CAIP2 && network !== X402_SOLANA_DEVNET_V1) {
+    return false;
+  }
+  if (USDC_SOLANA_DEVNET.mint === void 0 || requirement.asset !== USDC_SOLANA_DEVNET.mint) {
+    return false;
+  }
+  const amount = requirementAmount(requirement);
+  if (amount === null) {
+    return false;
+  }
+  return amount <= rule.maxUpstreamSubunits;
+}
+function selectAcceptableRequirement(accepts, rule) {
+  return accepts.find((requirement) => isAcceptableRequirement(requirement, rule));
+}
+function maxAcceptableQuote(accepts, rule) {
+  let worst = null;
+  for (const requirement of accepts) {
+    if (!isAcceptableRequirement(requirement, rule)) {
+      continue;
+    }
+    const amount = requirementAmount(requirement);
+    if (amount === null) {
+      continue;
+    }
+    if (worst === null || amount > worst) {
+      worst = amount;
+    }
+  }
+  return worst;
+}
+function buildRequirementsPolicy(rule) {
+  return function filterAcceptableRequirements(_x402Version, paymentRequirements) {
+    return paymentRequirements.filter((requirement) => isAcceptableRequirement(requirement, rule));
+  };
+}
+var PROBE_TIMEOUT_MS = 1e4;
+var MAX_PROBE_BODY_BYTES = 256 * 1024;
+var PROBE_CACHE_MAX_ENTRIES = 256;
+async function readTextCapped(response, maxBytes) {
+  const reader = response.body?.getReader();
+  if (reader === void 0) {
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength > maxBytes) {
+      throw new X402ProbeError(`402 body exceeds ${maxBytes} bytes`, 402);
+    }
+    return new TextDecoder().decode(buffer);
+  }
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => {
+      });
+      throw new X402ProbeError(`402 body exceeds ${maxBytes} bytes`, 402);
+    }
+    chunks.push(value);
+  }
+  const combined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    combined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(combined);
+}
+var X402ProbeError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "X402ProbeError";
+    this.status = status;
+  }
+};
+function normalizeV1Requirement(raw) {
+  return {
+    scheme: typeof raw.scheme === "string" ? raw.scheme : "",
+    network: typeof raw.network === "string" ? raw.network : "unknown:unknown",
+    asset: typeof raw.asset === "string" ? raw.asset : "",
+    payTo: typeof raw.payTo === "string" ? raw.payTo : "",
+    amount: typeof raw.maxAmountRequired === "string" ? raw.maxAmountRequired : "",
+    maxTimeoutSeconds: typeof raw.maxTimeoutSeconds === "number" ? raw.maxTimeoutSeconds : 60,
+    extra: raw.extra ?? {}
+  };
+}
+function parseV1Body(bodyText) {
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyText);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  const body = parsed;
+  if (body.x402Version !== 1 || !Array.isArray(body.accepts) || body.accepts.length === 0) {
+    return null;
+  }
+  const rawRequirements = body.accepts.filter(
+    (item) => typeof item === "object" && item !== null
+  );
+  if (rawRequirements.length === 0) {
+    return null;
+  }
+  const accepts = rawRequirements.map(normalizeV1Requirement);
+  const first = rawRequirements[0];
+  return {
+    x402Version: 1,
+    accepts,
+    resource: {
+      url: typeof first.resource === "string" ? first.resource : void 0,
+      description: typeof first.description === "string" ? first.description : void 0,
+      mimeType: typeof first.mimeType === "string" ? first.mimeType : void 0
+    }
+  };
+}
+async function probePaymentRequired(url, method, signal) {
+  const probeSignal = AbortSignal.timeout(PROBE_TIMEOUT_MS);
+  const response = await fetch(url, { method, signal: probeSignal, redirect: "error" });
+  if (response.status !== 402) {
+    await response.body?.cancel().catch(() => {
+    });
+    throw new X402ProbeError(
+      `expected HTTP 402 from ${url}, got ${response.status} - not an x402-paid endpoint (or it validates the request before the paywall; try the other method)`,
+      response.status
+    );
+  }
+  const headerValue = response.headers.get("PAYMENT-REQUIRED");
+  if (headerValue !== null) {
+    await response.body?.cancel().catch(() => {
+    });
+    try {
+      const paymentRequired = decodePaymentRequiredHeader(headerValue);
+      return {
+        x402Version: paymentRequired.x402Version,
+        accepts: paymentRequired.accepts,
+        resource: paymentRequired.resource
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new X402ProbeError(`could not decode PAYMENT-REQUIRED header: ${message}`, 402);
+    }
+  }
+  const bodyText = await readTextCapped(response, MAX_PROBE_BODY_BYTES).catch((error) => {
+    if (error instanceof X402ProbeError) {
+      throw error;
+    }
+    return "";
+  });
+  const v1 = parseV1Body(bodyText);
+  if (v1 !== null) {
+    return v1;
+  }
+  throw new X402ProbeError(
+    "got HTTP 402 but neither a v2 PAYMENT-REQUIRED header nor a v1 JSON body was parseable",
+    402
+  );
+}
+var PROBE_CACHE = /* @__PURE__ */ new Map();
+async function probePaymentRequiredCached(url, method, ttlMs) {
+  const key = `${method} ${url}`;
+  const cached = PROBE_CACHE.get(key);
+  const now = Date.now();
+  if (cached !== void 0 && now - cached.at < ttlMs) {
+    return cached.result;
+  }
+  const result = await probePaymentRequired(url, method);
+  PROBE_CACHE.delete(key);
+  PROBE_CACHE.set(key, { at: now, result });
+  while (PROBE_CACHE.size > PROBE_CACHE_MAX_ENTRIES) {
+    const oldest = PROBE_CACHE.keys().next().value;
+    if (oldest === void 0) {
+      break;
+    }
+    PROBE_CACHE.delete(oldest);
+  }
+  return result;
+}
+var X402_JOBS_FILE = ".x402-jobs.json";
+var X402_RESULTS_DIR = ".x402-results";
+function sanitizeJobId(jobId) {
+  return jobId.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128);
+}
+var X402JobStore = class {
+  jobsPath;
+  resultsDir;
+  queue = Promise.resolve();
+  constructor(agentDir) {
+    this.jobsPath = join(agentDir, X402_JOBS_FILE);
+    this.resultsDir = join(agentDir, X402_RESULTS_DIR);
+  }
+  /** Serialize read-modify-write cycles; a failed task must not wedge the queue. */
+  runExclusive(task) {
+    const scheduled = this.queue.then(task, task);
+    this.queue = scheduled.then(
+      function ignoreResult() {
+      },
+      function ignoreError() {
+      }
+    );
+    return scheduled;
+  }
+  async load() {
+    let raw;
+    try {
+      raw = await readFile(this.jobsPath, "utf-8");
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return {};
+      }
+      throw error;
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`x402 store ${this.jobsPath} is not a JSON object`);
+    }
+    return parsed;
+  }
+  async save(file) {
+    const tempPath = `${this.jobsPath}.tmp`;
+    await writeFile(tempPath, JSON.stringify(file, null, 2), "utf-8");
+    await rename(tempPath, this.jobsPath);
+  }
+  resultFilePath(jobId) {
+    return join(this.resultsDir, sanitizeJobId(jobId));
+  }
+  /**
+   * Atomically claim one paid attempt: increment iff still under BOTH caps
+   * (durable attempts and the monotonic signature count), and FLUSH before
+   * returning. The whole check-and-increment runs inside the serialization
+   * queue so concurrent `execute()` flows for the same jobId (dedup failure,
+   * crash-recovery racing the original) can never each read a stale count
+   * and all pass the budget gate - the money bound holds. The flush ordering
+   * errs on "an attempt happened", since the caller sends the payment
+   * immediately after a grant.
+   */
+  async claimPaidAttempt(jobId, maxAttempts, maxSignatures) {
+    return this.runExclusive(async () => {
+      const file = await this.load();
+      const now = Date.now();
+      const record = file[jobId] ?? { attempts: 0, created_at: now, updated_at: now };
+      const signatures = record.signatures ?? record.attempts;
+      if (signatures >= maxSignatures) {
+        return { granted: false, attempts: record.attempts, signatures, refusedBy: "signatures" };
+      }
+      if (record.attempts >= maxAttempts) {
+        return { granted: false, attempts: record.attempts, signatures, refusedBy: "attempts" };
+      }
+      record.attempts += 1;
+      record.signatures = signatures + 1;
+      record.updated_at = now;
+      file[jobId] = record;
+      await this.save(file);
+      return { granted: true, attempts: record.attempts, signatures: record.signatures };
+    });
+  }
+  /**
+   * Return one durable attempt slot after the upstream DEFINITIVELY refused
+   * the signed payment with a fresh 402 (an honest upstream did not settle,
+   * so no money moved). The monotonic `signatures` counter is intentionally
+   * NOT decremented: it is the adversarial bound against an upstream that
+   * settles the payment and lies with a 402 (see `claimPaidAttempt`).
+   */
+  async refundPaidAttempt(jobId) {
+    await this.runExclusive(async () => {
+      const file = await this.load();
+      const record = file[jobId];
+      if (record === void 0 || record.attempts === 0) {
+        return;
+      }
+      const signatures = record.signatures ?? record.attempts;
+      record.attempts -= 1;
+      record.signatures = signatures;
+      record.updated_at = Date.now();
+      await this.save(file);
+    });
+  }
+  /** Serialized point-in-time attempt count (test/inspection helper). */
+  async paidAttempts(jobId) {
+    return this.runExclusive(async () => {
+      const file = await this.load();
+      return file[jobId]?.attempts ?? 0;
+    });
+  }
+  /** Serialized point-in-time signed-payment count (test/inspection helper). */
+  async paymentSignatures(jobId) {
+    return this.runExclusive(async () => {
+      const file = await this.load();
+      const record = file[jobId];
+      return record === void 0 ? 0 : record.signatures ?? record.attempts;
+    });
+  }
+  async saveTextResult(jobId, data) {
+    await this.runExclusive(async () => {
+      const file = await this.load();
+      const now = Date.now();
+      const record = file[jobId] ?? { attempts: 0, created_at: now, updated_at: now };
+      record.result = { kind: "text", data };
+      record.updated_at = now;
+      file[jobId] = record;
+      await this.save(file);
+    });
+  }
+  /** Binary result: bytes hit disk BEFORE the record flush (crash-safe ordering). */
+  async saveFileResult(jobId, mime, bytes) {
+    const filePath = this.resultFilePath(jobId);
+    await mkdir(this.resultsDir, { recursive: true });
+    await writeFile(filePath, bytes);
+    await this.runExclusive(async () => {
+      const file = await this.load();
+      const now = Date.now();
+      const record = file[jobId] ?? { attempts: 0, created_at: now, updated_at: now };
+      record.result = { kind: "file", mime };
+      record.updated_at = now;
+      file[jobId] = record;
+      await this.save(file);
+    });
+    return filePath;
+  }
+  /**
+   * Completed result for this job, or null. A file record whose file went
+   * missing degrades to attempt-without-result (the budget still applies).
+   */
+  async getResult(jobId) {
+    const file = await this.load();
+    const result = file[jobId]?.result;
+    if (result === void 0) {
+      return null;
+    }
+    if (result.kind === "text") {
+      return { data: result.data };
+    }
+    const filePath = this.resultFilePath(jobId);
+    try {
+      const fileStat = await stat(filePath);
+      if (!fileStat.isFile()) {
+        return null;
+      }
+    } catch {
+      return null;
+    }
+    return { data: "", outputMime: result.mime, filePath };
+  }
+  /** Drop records (and their result files) older than the cache TTL. */
+  async sweepExpired(now = Date.now()) {
+    await this.runExclusive(async () => {
+      const file = await this.load();
+      let changed = false;
+      for (const [jobId, record] of Object.entries(file)) {
+        if (now - record.updated_at <= X402_CACHE_TTL_MS) {
+          continue;
+        }
+        delete file[jobId];
+        changed = true;
+        await rm(this.resultFilePath(jobId), { force: true }).catch(() => {
+        });
+      }
+      if (changed) {
+        await this.save(file);
+      }
+    });
+  }
+};
+
+// src/x402/driver.ts
+var CUSTOMER_INPUT_TOO_LARGE = "Input too large for this skill.";
+function jsonContentType(text) {
+  const trimmed = text.trimStart();
+  if (trimmed.length === 0 || trimmed[0] !== "{" && trimmed[0] !== "[") {
+    return false;
+  }
+  try {
+    JSON.parse(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isTextContentType(contentType) {
+  const mime = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  return mime.startsWith("text/") || mime === "application/json" || mime.endsWith("+json");
+}
+async function readBodyCapped(response, maxBytes) {
+  const reader = response.body?.getReader();
+  if (reader === void 0) {
+    const buffer = new Uint8Array(await response.arrayBuffer());
+    if (buffer.byteLength > maxBytes) {
+      throw new X402PermanentError(`upstream response too large (> ${maxBytes} bytes)`);
+    }
+    return buffer;
+  }
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => {
+      });
+      throw new X402PermanentError(`upstream response too large (> ${maxBytes} bytes)`);
+    }
+    chunks.push(value);
+  }
+  const combined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    combined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return combined;
+}
+async function capChallengeResponse(response) {
+  if (response.status !== 402) {
+    return response;
+  }
+  const bytes = await readBodyCapped(response, X402_MAX_CHALLENGE_BYTES);
+  return new Response(bytes, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
+  });
+}
+function abortableDelay(ms, signal) {
+  return new Promise((resolve3) => {
+    if (signal?.aborted) {
+      resolve3(false);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve3(false);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve3(true);
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var X402Driver = class {
+  constructor(options) {
+    this.options = options;
+    this.store = new X402JobStore(options.agentDir);
+    this.rpc = createSolanaRpc(options.rpcUrl);
+    this.store.sweepExpired().catch(() => {
+    });
+  }
+  store;
+  rpc;
+  signerPromise = null;
+  repriceHintLogged = /* @__PURE__ */ new Set();
+  log(message) {
+    (this.options.log ?? console.log)(`[x402] ${message}`);
+  }
+  getSigner() {
+    const secret = this.options.solanaSecretKeyBase58;
+    if (secret === void 0 || secret.length === 0) {
+      return Promise.reject(
+        new X402PreflightError(
+          "bridge wallet missing: .secrets.json has no solana_secret_key (run `npx @elisym/cli x402 add` to set it up)"
+        )
+      );
+    }
+    if (this.signerPromise === null) {
+      this.signerPromise = signerFromSecretKeyBase58(secret);
+    }
+    return this.signerPromise;
+  }
+  /** The single-wallet invariant: revenue lands where the upstream payer spends from. */
+  async assertWalletInvariant() {
+    const signer = await this.getSigner();
+    const paymentsAddress = this.options.paymentsAddress;
+    if (paymentsAddress === void 0 || paymentsAddress.length === 0) {
+      throw new X402PreflightError(
+        "elisym.yaml has no payments[] entry: revenue would not refill the bridge wallet (run `npx @elisym/cli x402 add` to fix)"
+      );
+    }
+    if (signer.address !== paymentsAddress) {
+      throw new X402PreflightError(
+        `wallet invariant violated: payments[].address (${paymentsAddress}) differs from the solana_secret_key address (${signer.address}); revenue would accumulate in one wallet while jobs drain the other - align them (re-run \`npx @elisym/cli x402 add\` or fix elisym.yaml)`
+      );
+    }
+    return signer;
+  }
+  assertInputRules(job, input) {
+    const { params } = job;
+    if (params.method === "GET" && params.queryParam !== void 0) {
+      const encodedBytes = Buffer.byteLength(encodeURIComponent(input.data), "utf8");
+      if (encodedBytes > X402_GET_INPUT_MAX_ENCODED_BYTES) {
+        throw new X402PreflightError(
+          `GET input too large: ${encodedBytes} percent-encoded bytes (max ${X402_GET_INPUT_MAX_ENCODED_BYTES})`,
+          CUSTOMER_INPUT_TOO_LARGE
+        );
+      }
+    }
+    const inputBytes = Buffer.byteLength(input.data, "utf8");
+    if (inputBytes > params.maxInputBytes) {
+      throw new X402PreflightError(
+        `input too large: ${inputBytes} bytes (skill x402_max_input_bytes=${params.maxInputBytes})`,
+        CUSTOMER_INPUT_TOO_LARGE
+      );
+    }
+  }
+  async preflight(job, input) {
+    const cached = await this.store.getResult(input.jobId);
+    if (cached !== null) {
+      return;
+    }
+    const signer = await this.assertWalletInvariant();
+    if (job.asset.mint !== USDC_SOLANA_DEVNET.mint || USDC_SOLANA_DEVNET.mint === void 0) {
+      throw new X402PreflightError(
+        `x402 skills must be priced in devnet USDC (skill "${job.skillName}" is priced in ${job.asset.symbol}); the margin check compares the elisym price to the upstream USDC quote - re-run \`npx @elisym/cli x402 add\``
+      );
+    }
+    this.assertInputRules(job, input);
+    const rule = { maxUpstreamSubunits: job.params.maxUpstreamSubunits };
+    let probe;
+    try {
+      probe = await probePaymentRequiredCached(
+        job.params.url,
+        job.params.method,
+        X402_PROBE_TTL_MS
+      );
+    } catch (error) {
+      if (error instanceof X402ProbeError) {
+        throw new X402PreflightError(`upstream probe failed: ${error.message}`);
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      throw new X402PreflightError(`upstream unreachable: ${message}`);
+    }
+    const quote = maxAcceptableQuote(probe.accepts, rule);
+    if (quote === null) {
+      throw new X402PreflightError(
+        "no acceptable upstream payment requirement: network/asset/scheme mismatch or the live quote exceeds x402_max_upstream (if the upstream repriced, re-run `npx @elisym/cli x402 add` to regenerate the skill)"
+      );
+    }
+    if (quote < job.params.maxUpstreamSubunits && !this.repriceHintLogged.has(job.skillName)) {
+      this.repriceHintLogged.add(job.skillName);
+      this.log(
+        `upstream for "${job.skillName}" now quotes ${formatAssetAmount(USDC_SOLANA_DEVNET, quote)} (your price was computed from ${formatAssetAmount(USDC_SOLANA_DEVNET, job.params.maxUpstreamSubunits)}); re-run \`npx @elisym/cli x402 add\` to reprice`
+      );
+    }
+    const balance = await fetchUsdcBalance(this.rpc, address(signer.address));
+    if (balance < quote) {
+      throw new X402PreflightError(
+        `bridge float insufficient: ${formatAssetAmount(USDC_SOLANA_DEVNET, balance)} USDC in ${signer.address}, upstream quotes ${formatAssetAmount(USDC_SOLANA_DEVNET, quote)} - top up the wallet`
+      );
+    }
+    const feeBps = await this.options.getFeeBps();
+    const fee = calculateProtocolFee(job.priceSubunits, feeBps);
+    const net = BigInt(job.priceSubunits - fee);
+    if (net < quote) {
+      throw new X402PreflightError(
+        `negative margin: net revenue ${formatAssetAmount(USDC_SOLANA_DEVNET, net)} (price minus ${feeBps} bps protocol fee) is below the upstream quote ${formatAssetAmount(USDC_SOLANA_DEVNET, quote)} - re-run \`npx @elisym/cli x402 add\` to reprice`
+      );
+    }
+  }
+  /**
+   * Instrumented fetch injected into the payment wrapper. The wrapper calls
+   * it for the initial unpaid request (no headers) and, after signing, for
+   * the paid retry (carrying `PAYMENT-SIGNATURE`). ONLY the paid request
+   * claims a budget slot, and it does so ATOMICALLY: `claimPaidAttempt`
+   * increments-or-refuses inside the store's serialization queue, so no set
+   * of concurrent `execute()` flows for one jobId can each pass a stale
+   * check and pay past the budget caps. A refusal throws BEFORE
+   * `globalThis.fetch` so no payment is sent.
+   */
+  buildInstrumentedFetch(jobId, attemptState) {
+    const store = this.store;
+    return async function instrumentedFetch(info, init) {
+      const request = new Request(info, init);
+      if (request.headers.has("PAYMENT-SIGNATURE") || request.headers.has("X-PAYMENT")) {
+        const claim = await store.claimPaidAttempt(
+          jobId,
+          X402_MAX_PAID_ATTEMPTS,
+          X402_MAX_PAYMENT_SIGNATURES
+        );
+        if (!claim.granted) {
+          throw new X402PermanentError(
+            claim.refusedBy === "signatures" ? `signed payment budget exhausted (${claim.signatures}/${X402_MAX_PAYMENT_SIGNATURES} payments signed for this job) - refusing to sign another` : `paid attempt budget exhausted (${claim.attempts}/${X402_MAX_PAID_ATTEMPTS}) - refusing to pay the upstream again`
+          );
+        }
+        attemptState.paymentSent = true;
+      }
+      const response = await globalThis.fetch(new Request(request, { redirect: "error" }));
+      return capChallengeResponse(response);
+    };
+  }
+  buildClient(signer, rule) {
+    const scheme = new ExactSvmScheme(signer, { rpcUrl: this.options.rpcUrl });
+    return x402Client.fromConfig({
+      schemes: [{ network: X402_SOLANA_DEVNET_CAIP2, client: scheme }],
+      policies: [buildRequirementsPolicy(rule)]
+    }).registerV1(X402_SOLANA_DEVNET_V1, scheme);
+  }
+  classifyWrapperError(error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      return error;
+    }
+    if (error instanceof X402PermanentError || error instanceof X402TransientError) {
+      return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("Failed to create payment payload")) {
+      return new X402PermanentError(
+        `payment refused by policy (upstream likely repriced above x402_max_upstream): ${message}`
+      );
+    }
+    return new X402TransientError(`upstream request failed: ${message}`);
+  }
+  classifyStatus(status) {
+    if (status === 402) {
+      return new X402TransientError("upstream still returned 402 after a payment attempt", status);
+    }
+    if (status === 429 || status >= 500) {
+      return new X402TransientError(`upstream returned ${status}`, status);
+    }
+    return new X402PermanentError(`upstream returned ${status}`);
+  }
+  async execute(job, input, signal) {
+    const cached = await this.store.getResult(input.jobId);
+    if (cached !== null) {
+      this.log(`job ${input.jobId.slice(0, 8)}: delivering cached upstream result (no re-payment)`);
+      return cached;
+    }
+    if (input.filePath !== void 0) {
+      throw new X402PermanentError(
+        "file inputs are not supported by x402 bridge skills (attachment exceeded the text re-inline cap)"
+      );
+    }
+    const inputBytes = Buffer.byteLength(input.data, "utf8");
+    if (inputBytes > job.params.maxInputBytes) {
+      throw new X402PermanentError(
+        `input exceeds x402_max_input_bytes after materialization: ${inputBytes} > ${job.params.maxInputBytes}`
+      );
+    }
+    const requestUrl = new URL(job.params.url);
+    const headers = {};
+    let body;
+    if (job.params.method === "GET") {
+      if (job.params.queryParam !== void 0 && input.data.length > 0) {
+        requestUrl.searchParams.set(job.params.queryParam, input.data);
+      }
+    } else {
+      body = input.data;
+      headers["content-type"] = jsonContentType(input.data) ? "application/json" : "text/plain";
+    }
+    const signer = await this.assertWalletInvariant();
+    const rule = { maxUpstreamSubunits: job.params.maxUpstreamSubunits };
+    const client = this.buildClient(signer, rule);
+    const jobTag = input.jobId.slice(0, 8);
+    let freeRetriesUsed = 0;
+    let refundedRetriesUsed = 0;
+    while (true) {
+      const attemptState = { paymentSent: false };
+      try {
+        return await this.attemptUpstream(
+          job,
+          requestUrl,
+          headers,
+          body,
+          input.jobId,
+          client,
+          attemptState,
+          signal
+        );
+      } catch (error) {
+        if (!(error instanceof X402TransientError)) {
+          throw error;
+        }
+        if (attemptState.paymentSent) {
+          if (error.upstreamStatus !== 402) {
+            throw error;
+          }
+          try {
+            await this.store.refundPaidAttempt(input.jobId);
+          } catch (refundError) {
+            const message = refundError instanceof Error ? refundError.message : String(refundError);
+            this.log(
+              `job ${jobTag}: could not refund the refused payment attempt (${message}) - keeping the slot consumed`
+            );
+            throw error;
+          }
+          if (refundedRetriesUsed >= X402_REFUNDED_RETRIES) {
+            throw error;
+          }
+          refundedRetriesUsed += 1;
+          this.log(
+            `job ${jobTag}: upstream refused the signed payment with a fresh 402 (likely expired blockhash) - attempt slot refunded, retrying with a fresh payment`
+          );
+          continue;
+        }
+        const freeRetryDelays = this.options.freeRetryDelaysMs ?? X402_FREE_RETRY_DELAYS_MS;
+        const delayMs = freeRetryDelays[freeRetriesUsed];
+        if (delayMs === void 0) {
+          throw error;
+        }
+        freeRetriesUsed += 1;
+        this.log(
+          `job ${jobTag}: transient failure before any payment (${error.message}) - inline retry ${freeRetriesUsed}/${freeRetryDelays.length} in ${delayMs}ms`
+        );
+        const slept = await abortableDelay(delayMs, signal);
+        if (!slept) {
+          throw error;
+        }
+      }
+    }
+  }
+  /** One full payment-wrapper pass against the upstream; throws classified errors. */
+  async attemptUpstream(job, requestUrl, headers, body, jobId, client, attemptState, signal) {
+    const fetchWithPayment = wrapFetchWithPayment(
+      this.buildInstrumentedFetch(jobId, attemptState),
+      client
+    );
+    let response;
+    try {
+      response = await fetchWithPayment(requestUrl, {
+        method: job.params.method,
+        headers,
+        body,
+        signal
+      });
+    } catch (error) {
+      throw this.classifyWrapperError(error);
+    }
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => {
+      });
+      throw this.classifyStatus(response.status);
+    }
+    let bytes;
+    try {
+      bytes = await readBodyCapped(response, X402_MAX_RESPONSE_BYTES);
+    } catch (error) {
+      throw this.classifyWrapperError(error);
+    }
+    const contentType = response.headers.get("content-type") ?? "application/octet-stream";
+    if (isTextContentType(contentType)) {
+      const data = new TextDecoder().decode(bytes);
+      await this.store.saveTextResult(jobId, data);
+      return { data };
+    }
+    const mime = contentType.split(";")[0]?.trim() ?? "application/octet-stream";
+    const filePath = await this.store.saveFileResult(jobId, mime, bytes);
+    return { data: "", outputMime: mime, filePath };
+  }
+};
+
 // src/commands/start.ts
 async function cmdStart(nameArg, options = {}) {
   const cwd = process.cwd();
@@ -4418,6 +5365,52 @@ async function cmdStart(nameArg, options = {}) {
     agentName,
     agentDescription: loaded.yaml.description ?? ""
   };
+  const x402Skills = allSkills.filter((skill) => skill.mode === "x402");
+  let x402InvariantBroken;
+  if (x402Skills.length > 0) {
+    const solanaSecretKey = loaded.secrets.solana_secret_key;
+    if (solanaSecretKey === void 0 || solanaSecretKey.length === 0) {
+      x402InvariantBroken = "no solana_secret_key in .secrets.json";
+    } else if (!solanaAddress) {
+      x402InvariantBroken = "no payments[] entry in elisym.yaml";
+    } else {
+      const bridgeSigner = await signerFromSecretKeyBase58(solanaSecretKey);
+      if (bridgeSigner.address !== solanaAddress) {
+        x402InvariantBroken = `payments[].address (${solanaAddress}) differs from the solana_secret_key address (${bridgeSigner.address})`;
+      }
+    }
+    for (const skill of x402Skills) {
+      if (skill.asset.mint !== USDC_SOLANA_DEVNET.mint) {
+        console.warn(
+          `  ! x402 skill "${skill.name}" is priced in ${skill.asset.symbol}, not devnet USDC - every job will be refused at preflight. Re-run \`npx @elisym/cli x402 add\`.`
+        );
+      }
+    }
+    if (x402InvariantBroken !== void 0) {
+      console.warn(`  ! x402 wallet invariant broken: ${x402InvariantBroken}.`);
+      console.warn(
+        "  ! x402 skills will NOT be advertised and their jobs will be refused before payment."
+      );
+      console.warn("  ! Fix: re-run `npx @elisym/cli x402 add` or align elisym.yaml with the key.");
+    }
+    const x402RpcUrl = getRpcUrl();
+    async function fetchLiveFeeBps() {
+      const config = await getProtocolConfig(
+        createSolanaRpc(x402RpcUrl),
+        getProtocolProgramId("devnet"),
+        { forceRefresh: true }
+      );
+      return config.feeBps;
+    }
+    skillCtx.x402Driver = new X402Driver({
+      agentDir: loaded.dir,
+      paymentsAddress: solanaAddress,
+      solanaSecretKeyBase58: loaded.secrets.solana_secret_key,
+      rpcUrl: x402RpcUrl,
+      getFeeBps: fetchLiveFeeBps,
+      log: (message) => console.log(`  ${message}`)
+    });
+  }
   console.log("  Connecting to relays and publishing capabilities...");
   const identity = ElisymIdentity.fromHex(loaded.secrets.nostr_secret_key);
   const relays = loaded.yaml.relays.length > 0 ? loaded.yaml.relays : [...RELAYS];
@@ -4564,7 +5557,7 @@ async function cmdStart(nameArg, options = {}) {
   }
   const kinds = [jobRequestKind(DEFAULT_KIND_OFFSET)];
   function buildCard(skill) {
-    const isStatic = skill.mode === "static-file" || skill.mode === "static-script";
+    const isStatic = skill.mode === "static-file" || skill.mode === "static-script" || skill.noInput === true;
     return {
       name: skill.name,
       description: skill.description,
@@ -4608,6 +5601,14 @@ async function cmdStart(nameArg, options = {}) {
       );
       continue;
     }
+    if (skill.mode === "x402" && x402InvariantBroken !== void 0) {
+      console.warn(`  ! Not advertising "${skill.name}" - x402 wallet invariant broken.`);
+      logger.warn(
+        { event: "publish_skipped_x402_invariant", kind: 31990, skill: skill.name },
+        "capability not advertised - x402 wallet invariant broken"
+      );
+      continue;
+    }
     try {
       await client.discovery.publishCapability(identity, buildCard(skill), kinds);
       cardsPublished += 1;
@@ -4661,6 +5662,9 @@ async function cmdStart(nameArg, options = {}) {
   const ledger = new JobLedger(paths.jobs);
   const irohTransport = createIrohTransport({ storePath: join(loaded.dir, ".iroh") });
   await ensureGitignoreHasIrohEntry(dirname(loaded.dir));
+  if (x402Skills.length > 0) {
+    await ensureGitignoreHasX402Entries(dirname(loaded.dir));
+  }
   const runtimeConfig = {
     paymentTimeoutSecs: DEFAULTS.PAYMENT_EXPIRY_SECS,
     maxConcurrentJobs: MAX_CONCURRENT_JOBS,
@@ -4923,6 +5927,431 @@ async function cmdWallet(name) {
   console.log(`  USDC balance: ${formatAssetAmount(USDC_SOLANA_DEVNET, usdcBalance)}
 `);
 }
+var BPS_DENOMINATOR = 1e4;
+var DEFAULT_MARGIN_BPS = 1e3;
+var SOLANA_MAINNET_CAIP2 = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+var CIRCLE_FAUCET_URL = "https://faucet.circle.com";
+function fail(message) {
+  console.error(`
+  ! ${message}
+`);
+  process.exit(1);
+}
+function sanitizeUpstreamText(raw, maxLength) {
+  let withoutControls = "";
+  for (const char of raw) {
+    const code = char.codePointAt(0) ?? 0;
+    withoutControls += code < 32 || code === 127 ? " " : char;
+  }
+  return withoutControls.replace(/—/g, "-").replace(/\s+/g, " ").trim().slice(0, maxLength).trim();
+}
+function slugFromUrl(url) {
+  const pathPart = url.pathname.replace(/\/+$/, "").split("/").filter(Boolean).pop() ?? "";
+  const host = url.hostname.replace(/^www\./, "").split(".")[0] ?? "x402";
+  return pathPart.length > 0 ? `${host}-${pathPart}` : host;
+}
+function parseMarginBps(raw) {
+  if (raw === void 0) {
+    return DEFAULT_MARGIN_BPS;
+  }
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > 1e5) {
+    fail(`--margin-bps must be a non-negative integer (bps, 100 = 1%); got "${raw}"`);
+  }
+  return value;
+}
+async function parseImportedSecret(input) {
+  const trimmed = input.trim();
+  if (existsSync(trimmed)) {
+    const content = await readFile(trimmed, "utf-8");
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      throw new Error(`${trimmed} is not a valid solana-keygen JSON file`);
+    }
+    if (!Array.isArray(parsed) || parsed.length !== 64 || parsed.some(
+      (byte) => typeof byte !== "number" || !Number.isInteger(byte) || byte < 0 || byte > 255
+    )) {
+      throw new Error(`${trimmed} must contain a JSON array of 64 bytes (solana-keygen format)`);
+    }
+    return encodeSecretKeyBase58(new Uint8Array(parsed));
+  }
+  try {
+    await signerFromSecretKeyBase58(trimmed);
+  } catch {
+    throw new Error("not a readable file and not a valid base58-encoded 64-byte secret key");
+  }
+  return trimmed;
+}
+function computeBridgePriceSubunits(quote, marginBps, feeBps) {
+  if (feeBps >= BPS_DENOMINATOR) {
+    throw new Error(`feeBps ${feeBps} >= ${BPS_DENOMINATOR} - refusing zero/negative denominator`);
+  }
+  return BigInt(
+    new Decimal(quote.toString()).mul(BPS_DENOMINATOR + marginBps).div(BPS_DENOMINATOR - feeBps).toDecimalPlaces(0, Decimal.ROUND_CEIL).toString()
+  );
+}
+function buildSkillMd(input) {
+  const frontmatter = {
+    name: input.skillName,
+    description: input.description,
+    capabilities: input.capabilities,
+    price: input.priceDisplay,
+    token: "usdc",
+    mode: "x402",
+    x402_url: input.url,
+    x402_method: input.method,
+    ...input.queryParam !== void 0 ? { x402_query_param: input.queryParam } : {},
+    x402_max_upstream: Number(input.quote),
+    // GET input is dominated by the ~2KB percent-encoded query-string limit,
+    // so the byte cap is written for POST bridges only.
+    ...input.method === "POST" ? { x402_max_input_bytes: DEFAULT_X402_MAX_INPUT_BYTES } : {}
+  };
+  const bodyLines = [
+    `# ${input.skillName}`,
+    "",
+    "Operator notes for this x402 bridge skill (the executor ignores this body):",
+    "",
+    `- Upstream: ${input.url} (${input.method})`,
+    `- Upstream quote at generation time: ${formatAssetAmount(USDC_SOLANA_DEVNET, input.quote)} (= x402_max_upstream, the signing ceiling)`,
+    `- Price: ${input.priceDisplay} USDC (margin ${input.marginPercent}%, protocol fee ${input.feePercent}% at generation time)`,
+    "- To reprice after an upstream change, re-run:",
+    "",
+    "```bash",
+    `npx @elisym/cli x402 add ${input.url}`,
+    "```"
+  ];
+  return `---
+${YAML.stringify(frontmatter)}---
+
+${bodyLines.join("\n")}
+`;
+}
+function scanExistingSkills(skillsDir, candidateDTag, url) {
+  const scan = {};
+  let entries;
+  try {
+    entries = readdirSync(skillsDir);
+  } catch {
+    return scan;
+  }
+  for (const entry of entries) {
+    const skillMdPath = join(skillsDir, entry, "SKILL.md");
+    try {
+      if (!statSync(join(skillsDir, entry)).isDirectory()) {
+        continue;
+      }
+      const { frontmatter } = parseSkillMd(readFileSync(skillMdPath, "utf-8"));
+      if (typeof frontmatter.name !== "string") {
+        continue;
+      }
+      if (typeof frontmatter.x402_url === "string" && frontmatter.x402_url === url) {
+        scan.sameUrlDir = join(skillsDir, entry);
+        scan.sameUrlName = frontmatter.name;
+        continue;
+      }
+      let existingDTag;
+      try {
+        existingDTag = toDTag(frontmatter.name);
+      } catch {
+        continue;
+      }
+      if (existingDTag === candidateDTag) {
+        scan.dTagCollision = frontmatter.name;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return scan;
+}
+function describeUnacceptableAccepts(probe) {
+  const networks = [...new Set(probe.accepts.map((requirement) => String(requirement.network)))];
+  if (networks.length > 0 && networks.every((network) => network.startsWith("eip155:"))) {
+    return `the service accepts only EVM networks (${networks.join(", ")}) - not supported yet`;
+  }
+  if (networks.some((network) => network === SOLANA_MAINNET_CAIP2 || network === "solana")) {
+    return "the service settles on Solana mainnet - elisym currently runs on devnet (mainnet is on the roadmap)";
+  }
+  return `no exact-scheme devnet-USDC requirement found (service accepts: ${networks.join(", ") || "nothing parseable"})`;
+}
+async function cmdX402Add(url, agentName, options) {
+  const cwd = process.cwd();
+  const { default: inquirer } = await import('inquirer');
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(url);
+  } catch {
+    fail(`"${url}" is not a valid URL`);
+  }
+  const isLoopback = ["localhost", "127.0.0.1", "[::1]"].includes(parsedUrl.hostname);
+  if (parsedUrl.protocol !== "https:" && !(parsedUrl.protocol === "http:" && isLoopback)) {
+    fail("the upstream must be an https:// URL (plain http is allowed for localhost only)");
+  }
+  const methodRaw = (options.method ?? "POST").toUpperCase();
+  if (methodRaw !== "GET" && methodRaw !== "POST") {
+    fail(`--method must be GET or POST; got "${options.method}"`);
+  }
+  const method = methodRaw;
+  const marginBps = parseMarginBps(options.marginBps);
+  if (!agentName) {
+    const agents = await listAgents(cwd);
+    if (agents.length === 0) {
+      fail("no agents found - create one first: npx @elisym/cli init");
+    }
+    if (options.yes) {
+      fail("--yes needs an explicit agent argument: elisym x402 add <url> <agent> --yes");
+    }
+    const { selected } = await inquirer.prompt([
+      {
+        type: "list",
+        name: "selected",
+        message: "Add the bridge skill to which agent?",
+        choices: agents.map((agent) => ({
+          name: `${agent.name} (${agent.source})`,
+          value: agent.name
+        }))
+      }
+    ]);
+    agentName = selected;
+  }
+  const passphrase = process.env.ELISYM_PASSPHRASE;
+  const loaded = await loadAgent(agentName, cwd, passphrase);
+  console.log(`
+  Probing ${url} (${method}, unpaid)...`);
+  let probe;
+  try {
+    probe = await probePaymentRequired(url, method);
+  } catch (error) {
+    if (error instanceof X402ProbeError) {
+      fail(error.message);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    fail(`upstream unreachable: ${message}`);
+  }
+  const anyCeiling = { maxUpstreamSubunits: BigInt(Number.MAX_SAFE_INTEGER) };
+  const requirement = selectAcceptableRequirement(probe.accepts, anyCeiling);
+  if (requirement === void 0) {
+    fail(describeUnacceptableAccepts(probe));
+  }
+  const quote = requirementAmount(requirement);
+  if (quote === null || quote <= 0n) {
+    fail("the upstream quote is not a positive integer amount");
+  }
+  let solanaSecretKey = loaded.secrets.solana_secret_key;
+  if (solanaSecretKey === void 0 || solanaSecretKey.length === 0) {
+    let choice;
+    if (options.yes || options.generateWallet) {
+      if (!options.generateWallet) {
+        fail(
+          "this agent has no Solana wallet key. Run interactively to generate/import one, or pass --generate-wallet (a money-holding key is never created silently under --yes)."
+        );
+      }
+      choice = "generate";
+    } else {
+      const { walletChoice } = await inquirer.prompt([
+        {
+          type: "list",
+          name: "walletChoice",
+          message: "The bridge pays the upstream from the agent wallet, but .secrets.json has no solana_secret_key:",
+          choices: [
+            { name: "Generate a new wallet", value: "generate" },
+            { name: "Import an existing one (solana-keygen JSON file or base58)", value: "import" }
+          ]
+        }
+      ]);
+      choice = walletChoice;
+    }
+    if (choice === "generate") {
+      const wallet = await generateSolanaWallet();
+      solanaSecretKey = wallet.secretKeyBase58;
+    } else {
+      const { imported } = await inquirer.prompt([
+        {
+          // Masked: a pasted base58 secret key must not echo to the terminal
+          // scrollback (matches every other secret prompt in the CLI). A file
+          // path can still be pasted/drag-dropped under the mask.
+          type: "password",
+          mask: "*",
+          name: "imported",
+          message: "Path to a solana-keygen JSON file (or paste a base58 secret key):"
+        }
+      ]);
+      try {
+        solanaSecretKey = await parseImportedSecret(imported);
+      } catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+      }
+    }
+    await writeSecrets(
+      loaded.dir,
+      { ...loaded.secrets, solana_secret_key: solanaSecretKey },
+      passphrase
+    );
+    console.log("  Wallet key saved to .secrets.json");
+  }
+  const signer = await signerFromSecretKeyBase58(solanaSecretKey);
+  const solPayment = loaded.yaml.payments.find((entry) => entry.chain === "solana");
+  if (solPayment !== void 0 && solPayment.address !== signer.address) {
+    fail(
+      `wallet invariant violated: elisym.yaml payments[].address (${solPayment.address}) differs from the solana_secret_key address (${signer.address}).
+    Revenue must land in the wallet the bridge spends from, or the float never refills.
+    Fix: set payments[].address to the key address, or import the matching key.`
+    );
+  }
+  if (solPayment === void 0) {
+    console.log(
+      `  elisym.yaml has no Solana payments entry; adding address ${signer.address} (devnet).`
+    );
+    await writeYaml(loaded.dir, {
+      ...loaded.yaml,
+      payments: [
+        ...loaded.yaml.payments,
+        { chain: "solana", network: "devnet", address: signer.address }
+      ]
+    });
+  }
+  const rpc = createSolanaRpc(getRpcUrl());
+  const balance = await fetchUsdcBalance(rpc, address(signer.address));
+  let feeBps;
+  try {
+    const protocolConfig = await getProtocolConfig(rpc, getProtocolProgramId("devnet"), {
+      forceRefresh: true
+    });
+    feeBps = protocolConfig.feeBps;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    fail(`could not read the on-chain protocol config (fee): ${message}`);
+  }
+  if (feeBps >= BPS_DENOMINATOR) {
+    fail(
+      `protocol fee is ${feeBps} bps (>= 100%) - price math would divide by zero or go negative`
+    );
+  }
+  const priceSubunits = computeBridgePriceSubunits(quote, marginBps, feeBps);
+  const priceDisplay = new Decimal(priceSubunits.toString()).div(new Decimal(10).pow(USDC_SOLANA_DEVNET.decimals)).toString();
+  const protocolFee = calculateProtocolFee(Number(priceSubunits), feeBps);
+  const netMargin = priceSubunits - BigInt(protocolFee) - quote;
+  const fallbackName = slugFromUrl(parsedUrl);
+  const rawName = options.name ?? probe.resource?.serviceName ?? fallbackName;
+  const skillName = sanitizeUpstreamText(rawName, LIMITS.MAX_AGENT_NAME_LENGTH);
+  if (!/[a-zA-Z0-9]/.test(skillName)) {
+    fail(
+      `the upstream service name ("${rawName}") has no ASCII letters or digits - pass an explicit --name <skill-name>`
+    );
+  }
+  const candidateDTag = toDTag(skillName);
+  const description = sanitizeUpstreamText(
+    probe.resource?.description ?? `x402 bridge to ${parsedUrl.hostname}`,
+    LIMITS.MAX_DESCRIPTION_LENGTH
+  );
+  const capabilities = [candidateDTag];
+  const skillsDir = join(loaded.dir, "skills");
+  const scan = scanExistingSkills(skillsDir, candidateDTag, url);
+  let targetDir = join(skillsDir, candidateDTag);
+  if (scan.sameUrlDir !== void 0) {
+    if (!options.yes) {
+      const { update } = await inquirer.prompt([
+        {
+          type: "confirm",
+          name: "update",
+          message: `Skill "${scan.sameUrlName}" already bridges this URL - regenerate it with the fresh quote?`,
+          default: true
+        }
+      ]);
+      if (!update) {
+        fail("aborted");
+      }
+    }
+    targetDir = scan.sameUrlDir;
+  } else if (scan.dTagCollision !== void 0) {
+    fail(
+      `the generated name "${skillName}" collides with existing skill "${scan.dTagCollision}" (both map to d-tag "${candidateDTag}", which would replace its live discovery card) - pass a distinct --name`
+    );
+  } else if (existsSync(targetDir)) {
+    fail(`skill directory ${targetDir} already exists - pass a distinct --name`);
+  }
+  let queryParam = options.queryParam;
+  if (method === "GET" && queryParam === void 0 && !options.yes) {
+    const { param } = await inquirer.prompt([
+      {
+        type: "input",
+        name: "param",
+        message: "GET upstream: which query parameter should carry the buyer input? (empty = the skill takes no input)"
+      }
+    ]);
+    queryParam = param.trim() === "" ? void 0 : param.trim();
+  }
+  if (queryParam !== void 0 && parsedUrl.searchParams.has(queryParam)) {
+    fail(`--query-param "${queryParam}" collides with a parameter already present in the URL`);
+  }
+  if (method === "POST" && queryParam !== void 0) {
+    fail("--query-param only applies to GET upstreams (POST maps the input to the request body)");
+  }
+  const noInput = method === "GET" && queryParam === void 0;
+  const feePercent = new Decimal(feeBps).div(100).toString();
+  const marginPercent = new Decimal(marginBps).div(100).toString();
+  console.log("");
+  console.log(`  ${chalk.bold(skillName)}`);
+  console.log(`  ${description}`);
+  console.log("");
+  console.log(
+    `  Upstream     ${url} (${method}${queryParam !== void 0 ? `, input in ?${queryParam}=` : ""}${noInput ? ", no buyer input" : ""})`
+  );
+  console.log(`  Quote        ${formatAssetAmount(USDC_SOLANA_DEVNET, quote)}`);
+  console.log(
+    `  Your price   ${formatAssetAmount(USDC_SOLANA_DEVNET, priceSubunits)}  (margin ${marginPercent}% + protocol fee ${feePercent}%)`
+  );
+  console.log(`  Net margin   ${formatAssetAmount(USDC_SOLANA_DEVNET, netMargin)} per job`);
+  console.log(
+    `  Float        ${formatAssetAmount(USDC_SOLANA_DEVNET, balance)} in ${signer.address}`
+  );
+  if (balance < quote) {
+    console.log(
+      chalk.yellow(
+        `  ! Float below one upstream quote - fund the wallet with devnet USDC: ${CIRCLE_FAUCET_URL}`
+      )
+    );
+  }
+  console.log(`  Skill dir    ${targetDir}`);
+  console.log("");
+  if (!options.yes) {
+    const { confirmed } = await inquirer.prompt([
+      { type: "confirm", name: "confirmed", message: "Write the skill?", default: true }
+    ]);
+    if (!confirmed) {
+      fail("aborted");
+    }
+  }
+  const content = buildSkillMd({
+    skillName,
+    description,
+    capabilities,
+    priceDisplay,
+    url,
+    method,
+    queryParam,
+    quote,
+    marginPercent,
+    feePercent
+  });
+  const roundTrip = parseSkillMd(content);
+  validateSkillFrontmatter(roundTrip.frontmatter, roundTrip.systemPrompt, {
+    allowFreeSkills: false,
+    allowX402Skills: true
+  });
+  await mkdir(targetDir, { recursive: true });
+  await writeFile(join(targetDir, "SKILL.md"), content, "utf-8");
+  await ensureGitignoreHasX402Entries(dirname(loaded.dir));
+  console.log(`
+  Wrote ${join(targetDir, "SKILL.md")}`);
+  if (balance < quote) {
+    console.log(`  Next: fund the float (devnet USDC): ${CIRCLE_FAUCET_URL}`);
+  }
+  console.log(`  Start the agent: npx @elisym/cli start ${agentName}
+`);
+}
 function readPackageVersion() {
   try {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -4996,6 +6425,21 @@ program.command("list").description("List all agents (project-local and home-glo
   })
 );
 program.command("wallet [name]").description("Show wallet balance").action(safe(cmdWallet));
+var x402 = program.command("x402").description("Bridge x402-paid HTTP services into elisym skills");
+x402.command("add <url> [agent]").description("Generate a bridge skill from a live x402 endpoint (probes its 402 challenge)").option("--method <method>", "HTTP method for the upstream call: GET or POST (default POST)").option(
+  "--query-param <name>",
+  "GET only: query parameter carrying the buyer input (omitting it on GET makes a no-input skill)"
+).option(
+  "--margin-bps <bps>",
+  "Operator margin over the upstream quote in basis points (default 1000 = 10%)"
+).option("--name <skill-name>", "Override the generated skill name (also the discovery d-tag)").option(
+  "--generate-wallet",
+  "Non-interactive runs only: generate a new Solana wallet key when the agent has none"
+).option("--yes", "Skip confirmation prompts (requires an explicit agent argument)").action(
+  safe(async (url, agent, options) => {
+    await cmdX402Add(url, agent, options);
+  })
+);
 program.parse();
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map