@elisym/sdk 0.25.5 → 0.26.0

package/dist/skills.d.cts

@@ -65,6 +65,12 @@ interface SkillContext {
      * `llmOverride` (or undefined for the agent default).
      */
     getLlm?: (override?: SkillLlmOverride) => LlmClient | undefined;
+    /**
+     * x402 protocol driver for `mode: 'x402'` skills. Injected by the elisym
+     * CLI runtime; absent in SDK-only hosts (which also refuse to LOAD x402
+     * skills - see `LoadSkillsOptions.allowX402Skills`).
+     */
+    x402?: X402Invoker;
     agentName: string;
     agentDescription: string;
     signal?: AbortSignal;
@@ -75,10 +81,66 @@ interface SkillContext {
  * - `static-file`: return the contents of a fixed file. No input required.
  * - `static-script`: spawn a script with no stdin. No input required.
  * - `dynamic-script`: spawn a script and pipe the user's input to stdin.
+ * - `x402`: proxy the job to an x402-paid HTTP upstream; the host runtime pays
+ *   the upstream from the agent's wallet. Requires an x402-capable host (the
+ *   elisym CLI) that injects `SkillContext.x402` - gated at load time via
+ *   `LoadSkillsOptions.allowX402Skills`.
  *
- * Static modes set `card.static = true` so the webapp hides its input box.
+ * Static modes (and an x402 GET skill without a query param) set
+ * `card.static = true` so the webapp hides its input box.
+ */
+type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script' | 'x402';
+/**
+ * Static configuration of an x402 bridge skill, parsed from SKILL.md
+ * frontmatter (`x402_*` fields). All money values are integer subunits.
  */
-type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script';
+interface X402SkillParams {
+    /** Upstream resource URL (https only). */
+    url: string;
+    /** HTTP method for the upstream call. Buyer input maps to the POST body or a GET query param. */
+    method: 'GET' | 'POST';
+    /** Query parameter carrying the buyer input (GET only). Absent on GET => the skill takes no input. */
+    queryParam?: string;
+    /**
+     * Ceiling on the upstream quote in subunits of the upstream asset. The
+     * host's payment layer must refuse to sign anything above it - this is the
+     * operator's wallet protection against upstream repricing.
+     */
+    maxUpstreamSubunits: bigint;
+    /**
+     * Ceiling on the buyer input size in bytes (inline UTF-8 length, or an
+     * attachment's declared size). Enforced by the host BEFORE the customer
+     * pays - upstream request-body limits are opaque, so an oversized input
+     * would otherwise fail deterministically after payment.
+     */
+    maxInputBytes: number;
+}
+/** Upstream response mapped by Content-Type: text inline, anything else as a file. */
+interface X402ProxyResult {
+    data: string;
+    outputMime?: string;
+    /**
+     * Set for a non-text upstream body. The file is owned by the host's
+     * idempotency cache (delivery source for crash recovery) - the skill must
+     * NOT attach a cleanup callback for it; the cache's TTL sweep deletes it.
+     */
+    filePath?: string;
+}
+/**
+ * Host-provided x402 protocol driver. Implemented by the elisym CLI runtime
+ * (payment signing, requirement policies, idempotency, error classification
+ * all live host-side); the SDK's `X402ProxySkill` only delegates to it.
+ */
+interface X402Invoker {
+    /**
+     * Pre-payment gate: verify the wallet invariant, probe the live 402 quote
+     * against `maxUpstreamSubunits`, check balance/margin and the input-size
+     * rules. Throws to refuse the job before the customer pays.
+     */
+    preflight(params: X402SkillParams, input: SkillInput): Promise<void>;
+    /** Perform the paid upstream call (or return a cached result for this jobId). */
+    execute(params: X402SkillParams, input: SkillInput, signal?: AbortSignal): Promise<X402ProxyResult>;
+}
 interface ToolDef {
     name: string;
     description: string;
@@ -140,6 +202,14 @@ interface Skill {
     llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
+    /**
+     * Optional pre-payment gate. The runtime calls it BEFORE the customer pays
+     * (and before the job enters the ledger); throwing refuses the job with an
+     * error feedback and no payment. `input` is the pre-payment view: inline
+     * text, tags and jobId only - a file input is fetched after payment, so
+     * `filePath` is never set here.
+     */
+    preflight?(input: SkillInput, ctx: SkillContext): Promise<void>;
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
 }
 
@@ -400,6 +470,44 @@ declare class DynamicScriptSkill implements Skill {
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
 }
 
+interface X402ProxySkillParams {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    x402: X402SkillParams;
+    image?: string;
+    imageFile?: string;
+}
+/**
+ * Bridges a job to an x402-paid HTTP upstream. The skill itself is a thin
+ * adapter: the whole protocol (payment signing, requirement policies,
+ * idempotency cache, error classification) lives in the host-injected
+ * `SkillContext.x402` driver, mirroring how `mode: 'llm'` delegates to
+ * `ctx.getLlm`. Constructing this skill is gated at load time
+ * (`LoadSkillsOptions.allowX402Skills`), so an SDK-only host never
+ * advertises a capability it cannot execute.
+ */
+declare class X402ProxySkill implements Skill {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    mode: SkillMode;
+    image?: string;
+    imageFile?: string;
+    llmOverride?: SkillLlmOverride;
+    readonly x402: X402SkillParams;
+    constructor(params: X402ProxySkillParams);
+    /** GET upstream without a query param consumes no buyer input (card should be static). */
+    get noInput(): boolean;
+    private requireInvoker;
+    preflight(input: SkillInput, ctx: SkillContext): Promise<void>;
+    execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
+}
+
 /**
  * Resolve `value` relative to `rootDir` and reject anything that escapes
  * the root (`..` segments, absolute paths outside it, or the root itself).
@@ -410,6 +518,14 @@ declare class DynamicScriptSkill implements Skill {
 declare function resolveInsidePath(rootDir: string, value: string): string | null;
 
 declare const DEFAULT_MAX_TOOL_ROUNDS = 10;
+/**
+ * Default ceiling on buyer input size for x402 skills (bytes). Conservative:
+ * upstream request-body limits are opaque (express.json defaults to 100KB,
+ * nginx to 1MiB) and an over-limit POST fails only AFTER the customer paid.
+ * Operators raise it per skill via `x402_max_input_bytes` when the upstream
+ * is known to accept more; hard cap is `LIMITS.MAX_REINLINE_TEXT_BYTES`.
+ */
+declare const DEFAULT_X402_MAX_INPUT_BYTES = 100000;
 interface SkillFrontmatter {
     name?: unknown;
     description?: unknown;
@@ -478,6 +594,23 @@ interface SkillFrontmatter {
      * `execution_timeout_secs`, then to unlimited.
      */
     max_execution_secs?: unknown;
+    /** Required when mode === 'x402'. Upstream resource URL (https only). */
+    x402_url?: unknown;
+    /** HTTP method for the upstream call ('GET' | 'POST'). Default 'POST'. x402 mode only. */
+    x402_method?: unknown;
+    /** Query parameter carrying the buyer input. GET upstreams only; absent => skill takes no input. */
+    x402_query_param?: unknown;
+    /**
+     * Required when mode === 'x402'. Ceiling on the upstream quote in integer
+     * subunits of the upstream asset (recorded at `elisym x402 add` time). The
+     * host's payment layer refuses to sign anything above it.
+     */
+    x402_max_upstream?: unknown;
+    /**
+     * Ceiling on buyer input size in bytes (x402 mode only). Default
+     * `DEFAULT_X402_MAX_INPUT_BYTES`; hard cap `LIMITS.MAX_REINLINE_TEXT_BYTES`.
+     */
+    x402_max_input_bytes?: unknown;
 }
 interface ParsedSkill {
     name: string;
@@ -533,6 +666,14 @@ interface ParsedSkill {
      * then to unlimited.
      */
     executionTimeoutSecs?: number;
+    /** Set when mode === 'x402': the parsed `x402_*` frontmatter block. */
+    x402?: X402SkillParams;
+    /**
+     * True when the skill consumes no buyer input (x402 GET without a query
+     * param). Hosts mark the discovery card `static` so clients hide the input
+     * box instead of silently dropping what the buyer typed.
+     */
+    noInput?: boolean;
 }
 interface LoaderLogger {
     debug?(obj: Record<string, unknown>, msg?: string): void;
@@ -545,6 +686,14 @@ interface LoadSkillsOptions {
      * false: paid-only (plugin's historical behaviour).
      */
     allowFreeSkills?: boolean;
+    /**
+     * When true, `mode: 'x402'` skills load. Default false: an x402 skill
+     * needs a host runtime that injects `SkillContext.x402` (the elisym CLI);
+     * an SDK-only host (e.g. the ElizaOS plugin) must fail at load time -
+     * NOT after a customer has paid for a job the skill cannot execute.
+     * `loadSkillsFromDir` then skips the skill with a warning.
+     */
+    allowX402Skills?: boolean;
     logger?: LoaderLogger;
 }
 declare function parseSkillMd(content: string): {
@@ -559,4 +708,4 @@ declare function validateSkillFrontmatter(frontmatter: SkillFrontmatter, systemP
  */
 declare function loadSkillsFromDir(skillsDir: string, options?: LoadSkillsOptions): Skill[];
 
-export { type CompletionResult, DEFAULT_MAX_TOOL_ROUNDS, DEFAULT_SCRIPT_TIMEOUT_MS, DynamicScriptSkill, type DynamicScriptSkillParams, type LlmClient, type LlmClientConfig, type LlmProvider, type LoadSkillsOptions, type LoaderLogger, MAX_SCRIPT_OUTPUT, MAX_STATIC_FILE_SIZE, type ParsedSkill, type RunScriptOptions, type RunScriptResult, ScriptSkill, type ScriptSkillLogger, type ScriptSkillParams, type Skill, type SkillContext, type SkillFrontmatter, type SkillInput, type SkillLlmOverride, type SkillMode, type SkillOutput, SkillRateLimit, type SkillToolDef, StaticFileSkill, type StaticFileSkillParams, StaticScriptSkill, type StaticScriptSkillParams, type ToolCall, type ToolDef, type ToolResult, loadSkillsFromDir, parseSkillMd, resolveInsidePath, runScript, validateSkillFrontmatter };
+export { type CompletionResult, DEFAULT_MAX_TOOL_ROUNDS, DEFAULT_SCRIPT_TIMEOUT_MS, DEFAULT_X402_MAX_INPUT_BYTES, DynamicScriptSkill, type DynamicScriptSkillParams, type LlmClient, type LlmClientConfig, type LlmProvider, type LoadSkillsOptions, type LoaderLogger, MAX_SCRIPT_OUTPUT, MAX_STATIC_FILE_SIZE, type ParsedSkill, type RunScriptOptions, type RunScriptResult, ScriptSkill, type ScriptSkillLogger, type ScriptSkillParams, type Skill, type SkillContext, type SkillFrontmatter, type SkillInput, type SkillLlmOverride, type SkillMode, type SkillOutput, SkillRateLimit, type SkillToolDef, StaticFileSkill, type StaticFileSkillParams, StaticScriptSkill, type StaticScriptSkillParams, type ToolCall, type ToolDef, type ToolResult, type X402Invoker, type X402ProxyResult, X402ProxySkill, type X402ProxySkillParams, type X402SkillParams, loadSkillsFromDir, parseSkillMd, resolveInsidePath, runScript, validateSkillFrontmatter };

package/dist/skills.d.ts

@@ -65,6 +65,12 @@ interface SkillContext {
      * `llmOverride` (or undefined for the agent default).
      */
     getLlm?: (override?: SkillLlmOverride) => LlmClient | undefined;
+    /**
+     * x402 protocol driver for `mode: 'x402'` skills. Injected by the elisym
+     * CLI runtime; absent in SDK-only hosts (which also refuse to LOAD x402
+     * skills - see `LoadSkillsOptions.allowX402Skills`).
+     */
+    x402?: X402Invoker;
     agentName: string;
     agentDescription: string;
     signal?: AbortSignal;
@@ -75,10 +81,66 @@ interface SkillContext {
  * - `static-file`: return the contents of a fixed file. No input required.
  * - `static-script`: spawn a script with no stdin. No input required.
  * - `dynamic-script`: spawn a script and pipe the user's input to stdin.
+ * - `x402`: proxy the job to an x402-paid HTTP upstream; the host runtime pays
+ *   the upstream from the agent's wallet. Requires an x402-capable host (the
+ *   elisym CLI) that injects `SkillContext.x402` - gated at load time via
+ *   `LoadSkillsOptions.allowX402Skills`.
  *
- * Static modes set `card.static = true` so the webapp hides its input box.
+ * Static modes (and an x402 GET skill without a query param) set
+ * `card.static = true` so the webapp hides its input box.
+ */
+type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script' | 'x402';
+/**
+ * Static configuration of an x402 bridge skill, parsed from SKILL.md
+ * frontmatter (`x402_*` fields). All money values are integer subunits.
  */
-type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script';
+interface X402SkillParams {
+    /** Upstream resource URL (https only). */
+    url: string;
+    /** HTTP method for the upstream call. Buyer input maps to the POST body or a GET query param. */
+    method: 'GET' | 'POST';
+    /** Query parameter carrying the buyer input (GET only). Absent on GET => the skill takes no input. */
+    queryParam?: string;
+    /**
+     * Ceiling on the upstream quote in subunits of the upstream asset. The
+     * host's payment layer must refuse to sign anything above it - this is the
+     * operator's wallet protection against upstream repricing.
+     */
+    maxUpstreamSubunits: bigint;
+    /**
+     * Ceiling on the buyer input size in bytes (inline UTF-8 length, or an
+     * attachment's declared size). Enforced by the host BEFORE the customer
+     * pays - upstream request-body limits are opaque, so an oversized input
+     * would otherwise fail deterministically after payment.
+     */
+    maxInputBytes: number;
+}
+/** Upstream response mapped by Content-Type: text inline, anything else as a file. */
+interface X402ProxyResult {
+    data: string;
+    outputMime?: string;
+    /**
+     * Set for a non-text upstream body. The file is owned by the host's
+     * idempotency cache (delivery source for crash recovery) - the skill must
+     * NOT attach a cleanup callback for it; the cache's TTL sweep deletes it.
+     */
+    filePath?: string;
+}
+/**
+ * Host-provided x402 protocol driver. Implemented by the elisym CLI runtime
+ * (payment signing, requirement policies, idempotency, error classification
+ * all live host-side); the SDK's `X402ProxySkill` only delegates to it.
+ */
+interface X402Invoker {
+    /**
+     * Pre-payment gate: verify the wallet invariant, probe the live 402 quote
+     * against `maxUpstreamSubunits`, check balance/margin and the input-size
+     * rules. Throws to refuse the job before the customer pays.
+     */
+    preflight(params: X402SkillParams, input: SkillInput): Promise<void>;
+    /** Perform the paid upstream call (or return a cached result for this jobId). */
+    execute(params: X402SkillParams, input: SkillInput, signal?: AbortSignal): Promise<X402ProxyResult>;
+}
 interface ToolDef {
     name: string;
     description: string;
@@ -140,6 +202,14 @@ interface Skill {
     llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
+    /**
+     * Optional pre-payment gate. The runtime calls it BEFORE the customer pays
+     * (and before the job enters the ledger); throwing refuses the job with an
+     * error feedback and no payment. `input` is the pre-payment view: inline
+     * text, tags and jobId only - a file input is fetched after payment, so
+     * `filePath` is never set here.
+     */
+    preflight?(input: SkillInput, ctx: SkillContext): Promise<void>;
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
 }
 
@@ -400,6 +470,44 @@ declare class DynamicScriptSkill implements Skill {
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
 }
 
+interface X402ProxySkillParams {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    x402: X402SkillParams;
+    image?: string;
+    imageFile?: string;
+}
+/**
+ * Bridges a job to an x402-paid HTTP upstream. The skill itself is a thin
+ * adapter: the whole protocol (payment signing, requirement policies,
+ * idempotency cache, error classification) lives in the host-injected
+ * `SkillContext.x402` driver, mirroring how `mode: 'llm'` delegates to
+ * `ctx.getLlm`. Constructing this skill is gated at load time
+ * (`LoadSkillsOptions.allowX402Skills`), so an SDK-only host never
+ * advertises a capability it cannot execute.
+ */
+declare class X402ProxySkill implements Skill {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    mode: SkillMode;
+    image?: string;
+    imageFile?: string;
+    llmOverride?: SkillLlmOverride;
+    readonly x402: X402SkillParams;
+    constructor(params: X402ProxySkillParams);
+    /** GET upstream without a query param consumes no buyer input (card should be static). */
+    get noInput(): boolean;
+    private requireInvoker;
+    preflight(input: SkillInput, ctx: SkillContext): Promise<void>;
+    execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
+}
+
 /**
  * Resolve `value` relative to `rootDir` and reject anything that escapes
  * the root (`..` segments, absolute paths outside it, or the root itself).
@@ -410,6 +518,14 @@ declare class DynamicScriptSkill implements Skill {
 declare function resolveInsidePath(rootDir: string, value: string): string | null;
 
 declare const DEFAULT_MAX_TOOL_ROUNDS = 10;
+/**
+ * Default ceiling on buyer input size for x402 skills (bytes). Conservative:
+ * upstream request-body limits are opaque (express.json defaults to 100KB,
+ * nginx to 1MiB) and an over-limit POST fails only AFTER the customer paid.
+ * Operators raise it per skill via `x402_max_input_bytes` when the upstream
+ * is known to accept more; hard cap is `LIMITS.MAX_REINLINE_TEXT_BYTES`.
+ */
+declare const DEFAULT_X402_MAX_INPUT_BYTES = 100000;
 interface SkillFrontmatter {
     name?: unknown;
     description?: unknown;
@@ -478,6 +594,23 @@ interface SkillFrontmatter {
      * `execution_timeout_secs`, then to unlimited.
      */
     max_execution_secs?: unknown;
+    /** Required when mode === 'x402'. Upstream resource URL (https only). */
+    x402_url?: unknown;
+    /** HTTP method for the upstream call ('GET' | 'POST'). Default 'POST'. x402 mode only. */
+    x402_method?: unknown;
+    /** Query parameter carrying the buyer input. GET upstreams only; absent => skill takes no input. */
+    x402_query_param?: unknown;
+    /**
+     * Required when mode === 'x402'. Ceiling on the upstream quote in integer
+     * subunits of the upstream asset (recorded at `elisym x402 add` time). The
+     * host's payment layer refuses to sign anything above it.
+     */
+    x402_max_upstream?: unknown;
+    /**
+     * Ceiling on buyer input size in bytes (x402 mode only). Default
+     * `DEFAULT_X402_MAX_INPUT_BYTES`; hard cap `LIMITS.MAX_REINLINE_TEXT_BYTES`.
+     */
+    x402_max_input_bytes?: unknown;
 }
 interface ParsedSkill {
     name: string;
@@ -533,6 +666,14 @@ interface ParsedSkill {
      * then to unlimited.
      */
     executionTimeoutSecs?: number;
+    /** Set when mode === 'x402': the parsed `x402_*` frontmatter block. */
+    x402?: X402SkillParams;
+    /**
+     * True when the skill consumes no buyer input (x402 GET without a query
+     * param). Hosts mark the discovery card `static` so clients hide the input
+     * box instead of silently dropping what the buyer typed.
+     */
+    noInput?: boolean;
 }
 interface LoaderLogger {
     debug?(obj: Record<string, unknown>, msg?: string): void;
@@ -545,6 +686,14 @@ interface LoadSkillsOptions {
      * false: paid-only (plugin's historical behaviour).
      */
     allowFreeSkills?: boolean;
+    /**
+     * When true, `mode: 'x402'` skills load. Default false: an x402 skill
+     * needs a host runtime that injects `SkillContext.x402` (the elisym CLI);
+     * an SDK-only host (e.g. the ElizaOS plugin) must fail at load time -
+     * NOT after a customer has paid for a job the skill cannot execute.
+     * `loadSkillsFromDir` then skips the skill with a warning.
+     */
+    allowX402Skills?: boolean;
     logger?: LoaderLogger;
 }
 declare function parseSkillMd(content: string): {
@@ -559,4 +708,4 @@ declare function validateSkillFrontmatter(frontmatter: SkillFrontmatter, systemP
  */
 declare function loadSkillsFromDir(skillsDir: string, options?: LoadSkillsOptions): Skill[];
 
-export { type CompletionResult, DEFAULT_MAX_TOOL_ROUNDS, DEFAULT_SCRIPT_TIMEOUT_MS, DynamicScriptSkill, type DynamicScriptSkillParams, type LlmClient, type LlmClientConfig, type LlmProvider, type LoadSkillsOptions, type LoaderLogger, MAX_SCRIPT_OUTPUT, MAX_STATIC_FILE_SIZE, type ParsedSkill, type RunScriptOptions, type RunScriptResult, ScriptSkill, type ScriptSkillLogger, type ScriptSkillParams, type Skill, type SkillContext, type SkillFrontmatter, type SkillInput, type SkillLlmOverride, type SkillMode, type SkillOutput, SkillRateLimit, type SkillToolDef, StaticFileSkill, type StaticFileSkillParams, StaticScriptSkill, type StaticScriptSkillParams, type ToolCall, type ToolDef, type ToolResult, loadSkillsFromDir, parseSkillMd, resolveInsidePath, runScript, validateSkillFrontmatter };
+export { type CompletionResult, DEFAULT_MAX_TOOL_ROUNDS, DEFAULT_SCRIPT_TIMEOUT_MS, DEFAULT_X402_MAX_INPUT_BYTES, DynamicScriptSkill, type DynamicScriptSkillParams, type LlmClient, type LlmClientConfig, type LlmProvider, type LoadSkillsOptions, type LoaderLogger, MAX_SCRIPT_OUTPUT, MAX_STATIC_FILE_SIZE, type ParsedSkill, type RunScriptOptions, type RunScriptResult, ScriptSkill, type ScriptSkillLogger, type ScriptSkillParams, type Skill, type SkillContext, type SkillFrontmatter, type SkillInput, type SkillLlmOverride, type SkillMode, type SkillOutput, SkillRateLimit, type SkillToolDef, StaticFileSkill, type StaticFileSkillParams, StaticScriptSkill, type StaticScriptSkillParams, type ToolCall, type ToolDef, type ToolResult, type X402Invoker, type X402ProxyResult, X402ProxySkill, type X402ProxySkillParams, type X402SkillParams, loadSkillsFromDir, parseSkillMd, resolveInsidePath, runScript, validateSkillFrontmatter };

package/dist/skills.js

@@ -447,6 +447,53 @@ var DynamicScriptSkill = class {
     }
   }
 };
+
+// src/skills/x402ProxySkill.ts
+var X402ProxySkill = class {
+  name;
+  description;
+  capabilities;
+  priceSubunits;
+  asset;
+  mode = "x402";
+  image;
+  imageFile;
+  llmOverride;
+  x402;
+  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.image = params.image;
+    this.imageFile = params.imageFile;
+  }
+  /** GET upstream without a query param consumes no buyer input (card should be static). */
+  get noInput() {
+    return this.x402.method === "GET" && this.x402.queryParam === void 0;
+  }
+  requireInvoker(ctx) {
+    if (ctx.x402 === void 0) {
+      throw new Error(
+        `Skill "${this.name}": x402 skills require the elisym CLI runtime (no x402 driver in SkillContext)`
+      );
+    }
+    return ctx.x402;
+  }
+  async preflight(input, ctx) {
+    await this.requireInvoker(ctx).preflight(this.x402, input);
+  }
+  async execute(input, ctx) {
+    const result = await this.requireInvoker(ctx).execute(this.x402, input, ctx.signal);
+    return {
+      data: result.data,
+      outputMime: result.outputMime,
+      filePath: result.filePath
+    };
+  }
+};
 function resolveInsidePath(rootDir, value) {
   const root = resolve(rootDir);
   const candidate = resolve(root, value);
@@ -457,6 +504,10 @@ function resolveInsidePath(rootDir, value) {
   return candidate;
 }
 var LIMITS = {
+  // Ceiling above which a text/* attachment is NOT materialized back into a string
+  // (re-inlined into SkillInput.data) - the consumer gets a filePath / explicit
+  // fetch instead. Also bounds the in-memory git-diff buffer (memory-DoS guard).
+  MAX_REINLINE_TEXT_BYTES: 4194304,
   // Upper bound for execution budgets (`max_execution_secs` / `execution_timeout_secs`).
   // Distinct from MAX_TIMEOUT_SECS (the result-wait cap): execution budgets may be
   // hours, so this exists only to keep `secs * 1000` within Node's setTimeout limit
@@ -536,8 +587,10 @@ var VALID_MODES = [
   "llm",
   "static-file",
   "static-script",
-  "dynamic-script"
+  "dynamic-script",
+  "x402"
 ];
+var DEFAULT_X402_MAX_INPUT_BYTES = 1e5;
 function solToLamports(sol) {
   const asString = (typeof sol === "string" ? sol : String(sol)).trim();
   if (/^0+(?:\.0+)?$/.test(asString)) {
@@ -693,6 +746,11 @@ function validateLlmOverride(skillName, frontmatter, mode) {
   if (!hasProvider && !hasModel && !hasMaxTokens) {
     return void 0;
   }
+  if (mode === "x402") {
+    throw new Error(
+      `SKILL.md "${skillName}": "provider"/"model"/"max_tokens" are not valid in mode 'x402'`
+    );
+  }
   if (hasMaxTokens && mode !== "llm") {
     throw new Error(
       `SKILL.md "${skillName}": "max_tokens" is only valid in mode 'llm' (got '${mode}'). For script modes, control token limits inside the script.`
@@ -816,6 +874,114 @@ function validateMaxExecutionSecs(skillName, raw) {
   }
   return raw;
 }
+var X402_METHODS = ["GET", "POST"];
+function validateX402Config(skillName, frontmatter, mode, options) {
+  const fieldNames = [
+    "x402_url",
+    "x402_method",
+    "x402_query_param",
+    "x402_max_upstream",
+    "x402_max_input_bytes"
+  ];
+  const presentFields = fieldNames.filter(
+    (field) => frontmatter[field] !== void 0 && frontmatter[field] !== null
+  );
+  if (mode !== "x402") {
+    if (presentFields.length > 0) {
+      throw new Error(
+        `SKILL.md "${skillName}": "${presentFields[0]}" is only valid in mode 'x402'`
+      );
+    }
+    return void 0;
+  }
+  if (!options.allowX402Skills) {
+    throw new Error(
+      `SKILL.md "${skillName}": x402 skills require the elisym CLI runtime; this host cannot execute mode 'x402'`
+    );
+  }
+  if (typeof frontmatter.x402_url !== "string" || frontmatter.x402_url.length === 0) {
+    throw new Error(`SKILL.md "${skillName}": mode 'x402' requires "x402_url" (string)`);
+  }
+  let url;
+  try {
+    url = new URL(frontmatter.x402_url);
+  } catch {
+    throw new Error(`SKILL.md "${skillName}": "x402_url" is not a valid URL`);
+  }
+  const isLoopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) {
+    throw new Error(
+      `SKILL.md "${skillName}": "x402_url" must be an https:// URL (plain http is allowed for localhost only)`
+    );
+  }
+  let method = "POST";
+  if (frontmatter.x402_method !== void 0 && frontmatter.x402_method !== null) {
+    if (typeof frontmatter.x402_method !== "string" || !X402_METHODS.includes(frontmatter.x402_method)) {
+      throw new Error(
+        `SKILL.md "${skillName}": "x402_method" must be one of ${X402_METHODS.join(", ")}`
+      );
+    }
+    method = frontmatter.x402_method;
+  }
+  let queryParam;
+  if (frontmatter.x402_query_param !== void 0 && frontmatter.x402_query_param !== null) {
+    if (method !== "GET") {
+      throw new Error(
+        `SKILL.md "${skillName}": "x402_query_param" is only valid with x402_method 'GET' (POST maps the input to the request body)`
+      );
+    }
+    if (typeof frontmatter.x402_query_param !== "string" || frontmatter.x402_query_param.length === 0) {
+      throw new Error(`SKILL.md "${skillName}": "x402_query_param" must be a non-empty string`);
+    }
+    if (url.searchParams.has(frontmatter.x402_query_param)) {
+      throw new Error(
+        `SKILL.md "${skillName}": "x402_query_param" ("${frontmatter.x402_query_param}") collides with a parameter already present in "x402_url"`
+      );
+    }
+    queryParam = frontmatter.x402_query_param;
+  }
+  const rawMaxUpstream = frontmatter.x402_max_upstream;
+  if (rawMaxUpstream === void 0 || rawMaxUpstream === null) {
+    throw new Error(
+      `SKILL.md "${skillName}": mode 'x402' requires "x402_max_upstream" (integer subunits - the ceiling on the upstream quote)`
+    );
+  }
+  let maxUpstreamSubunits;
+  if (typeof rawMaxUpstream === "number" && Number.isSafeInteger(rawMaxUpstream)) {
+    maxUpstreamSubunits = BigInt(rawMaxUpstream);
+  } else if (typeof rawMaxUpstream === "string" && /^[0-9]+$/.test(rawMaxUpstream)) {
+    maxUpstreamSubunits = BigInt(rawMaxUpstream);
+  } else {
+    throw new Error(
+      `SKILL.md "${skillName}": "x402_max_upstream" must be a non-negative integer (subunits)`
+    );
+  }
+  if (maxUpstreamSubunits <= 0n) {
+    throw new Error(`SKILL.md "${skillName}": "x402_max_upstream" must be > 0`);
+  }
+  let maxInputBytes = DEFAULT_X402_MAX_INPUT_BYTES;
+  if (frontmatter.x402_max_input_bytes !== void 0 && frontmatter.x402_max_input_bytes !== null) {
+    const raw = frontmatter.x402_max_input_bytes;
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw <= 0) {
+      throw new Error(
+        `SKILL.md "${skillName}": "x402_max_input_bytes" must be a positive integer (bytes)`
+      );
+    }
+    if (raw > LIMITS.MAX_REINLINE_TEXT_BYTES) {
+      throw new Error(
+        `SKILL.md "${skillName}": "x402_max_input_bytes" must be <= ${LIMITS.MAX_REINLINE_TEXT_BYTES} (inputs above it never reach the skill as text)`
+      );
+    }
+    maxInputBytes = raw;
+  }
+  return {
+    url: frontmatter.x402_url,
+    method,
+    queryParam,
+    maxUpstreamSubunits,
+    maxInputBytes
+  };
+}
 function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
   if (typeof frontmatter.name !== "string" || frontmatter.name.length === 0) {
     throw new Error('SKILL.md: missing or invalid "name" field');
@@ -1008,6 +1174,7 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
     frontmatter.name,
     frontmatter.max_execution_secs
   );
+  const x402 = validateX402Config(frontmatter.name, frontmatter, mode, options);
   return {
     name: frontmatter.name,
     description: frontmatter.description,
@@ -1029,7 +1196,9 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
     inputMime,
     inputText,
     rateLimit,
-    executionTimeoutSecs
+    executionTimeoutSecs,
+    x402,
+    noInput: x402 === void 0 ? void 0 : x402.method === "GET" && x402.queryParam === void 0
   };
 }
 function buildSkillFromParsed(parsed, skillDir, logger) {
@@ -1108,6 +1277,23 @@ function buildSkillFromParsed(parsed, skillDir, logger) {
       };
       return parsed.mode === "dynamic-script" ? new DynamicScriptSkill({ ...scriptParams, outputMime: parsed.outputMime }) : new StaticScriptSkill(scriptParams);
     }
+    case "x402": {
+      if (parsed.x402 === void 0) {
+        throw new Error(
+          `SKILL.md "${parsed.name}": internal error - x402 config missing for mode 'x402'`
+        );
+      }
+      return new X402ProxySkill({
+        name: parsed.name,
+        description: parsed.description,
+        capabilities: parsed.capabilities,
+        priceSubunits: parsed.priceSubunits,
+        asset: parsed.asset,
+        x402: parsed.x402,
+        image: parsed.image,
+        imageFile
+      });
+    }
   }
 }
 function loadSkillsFromDir(skillsDir, options = {}) {
@@ -1143,6 +1329,6 @@ function loadSkillsFromDir(skillsDir, options = {}) {
   return skills;
 }
 
-export { DEFAULT_MAX_TOOL_ROUNDS, DEFAULT_SCRIPT_TIMEOUT_MS, DynamicScriptSkill, MAX_SCRIPT_OUTPUT, MAX_STATIC_FILE_SIZE, ScriptSkill, StaticFileSkill, StaticScriptSkill, loadSkillsFromDir, parseSkillMd, resolveInsidePath, runScript, validateSkillFrontmatter };
+export { DEFAULT_MAX_TOOL_ROUNDS, DEFAULT_SCRIPT_TIMEOUT_MS, DEFAULT_X402_MAX_INPUT_BYTES, DynamicScriptSkill, MAX_SCRIPT_OUTPUT, MAX_STATIC_FILE_SIZE, ScriptSkill, StaticFileSkill, StaticScriptSkill, X402ProxySkill, loadSkillsFromDir, parseSkillMd, resolveInsidePath, runScript, validateSkillFrontmatter };
 //# sourceMappingURL=skills.js.map
 //# sourceMappingURL=skills.js.map