@elisym/sdk 0.25.4 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/skills.d.cts CHANGED
@@ -65,6 +65,12 @@ interface SkillContext {
65
65
  * `llmOverride` (or undefined for the agent default).
66
66
  */
67
67
  getLlm?: (override?: SkillLlmOverride) => LlmClient | undefined;
68
+ /**
69
+ * x402 protocol driver for `mode: 'x402'` skills. Injected by the elisym
70
+ * CLI runtime; absent in SDK-only hosts (which also refuse to LOAD x402
71
+ * skills - see `LoadSkillsOptions.allowX402Skills`).
72
+ */
73
+ x402?: X402Invoker;
68
74
  agentName: string;
69
75
  agentDescription: string;
70
76
  signal?: AbortSignal;
@@ -75,10 +81,66 @@ interface SkillContext {
75
81
  * - `static-file`: return the contents of a fixed file. No input required.
76
82
  * - `static-script`: spawn a script with no stdin. No input required.
77
83
  * - `dynamic-script`: spawn a script and pipe the user's input to stdin.
84
+ * - `x402`: proxy the job to an x402-paid HTTP upstream; the host runtime pays
85
+ * the upstream from the agent's wallet. Requires an x402-capable host (the
86
+ * elisym CLI) that injects `SkillContext.x402` - gated at load time via
87
+ * `LoadSkillsOptions.allowX402Skills`.
78
88
  *
79
- * Static modes set `card.static = true` so the webapp hides its input box.
89
+ * Static modes (and an x402 GET skill without a query param) set
90
+ * `card.static = true` so the webapp hides its input box.
91
+ */
92
+ type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script' | 'x402';
93
+ /**
94
+ * Static configuration of an x402 bridge skill, parsed from SKILL.md
95
+ * frontmatter (`x402_*` fields). All money values are integer subunits.
80
96
  */
81
- type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script';
97
+ interface X402SkillParams {
98
+ /** Upstream resource URL (https only). */
99
+ url: string;
100
+ /** HTTP method for the upstream call. Buyer input maps to the POST body or a GET query param. */
101
+ method: 'GET' | 'POST';
102
+ /** Query parameter carrying the buyer input (GET only). Absent on GET => the skill takes no input. */
103
+ queryParam?: string;
104
+ /**
105
+ * Ceiling on the upstream quote in subunits of the upstream asset. The
106
+ * host's payment layer must refuse to sign anything above it - this is the
107
+ * operator's wallet protection against upstream repricing.
108
+ */
109
+ maxUpstreamSubunits: bigint;
110
+ /**
111
+ * Ceiling on the buyer input size in bytes (inline UTF-8 length, or an
112
+ * attachment's declared size). Enforced by the host BEFORE the customer
113
+ * pays - upstream request-body limits are opaque, so an oversized input
114
+ * would otherwise fail deterministically after payment.
115
+ */
116
+ maxInputBytes: number;
117
+ }
118
+ /** Upstream response mapped by Content-Type: text inline, anything else as a file. */
119
+ interface X402ProxyResult {
120
+ data: string;
121
+ outputMime?: string;
122
+ /**
123
+ * Set for a non-text upstream body. The file is owned by the host's
124
+ * idempotency cache (delivery source for crash recovery) - the skill must
125
+ * NOT attach a cleanup callback for it; the cache's TTL sweep deletes it.
126
+ */
127
+ filePath?: string;
128
+ }
129
+ /**
130
+ * Host-provided x402 protocol driver. Implemented by the elisym CLI runtime
131
+ * (payment signing, requirement policies, idempotency, error classification
132
+ * all live host-side); the SDK's `X402ProxySkill` only delegates to it.
133
+ */
134
+ interface X402Invoker {
135
+ /**
136
+ * Pre-payment gate: verify the wallet invariant, probe the live 402 quote
137
+ * against `maxUpstreamSubunits`, check balance/margin and the input-size
138
+ * rules. Throws to refuse the job before the customer pays.
139
+ */
140
+ preflight(params: X402SkillParams, input: SkillInput): Promise<void>;
141
+ /** Perform the paid upstream call (or return a cached result for this jobId). */
142
+ execute(params: X402SkillParams, input: SkillInput, signal?: AbortSignal): Promise<X402ProxyResult>;
143
+ }
82
144
  interface ToolDef {
83
145
  name: string;
84
146
  description: string;
@@ -140,6 +202,14 @@ interface Skill {
140
202
  llmOverride?: SkillLlmOverride;
141
203
  image?: string;
142
204
  imageFile?: string;
205
+ /**
206
+ * Optional pre-payment gate. The runtime calls it BEFORE the customer pays
207
+ * (and before the job enters the ledger); throwing refuses the job with an
208
+ * error feedback and no payment. `input` is the pre-payment view: inline
209
+ * text, tags and jobId only - a file input is fetched after payment, so
210
+ * `filePath` is never set here.
211
+ */
212
+ preflight?(input: SkillInput, ctx: SkillContext): Promise<void>;
143
213
  execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
144
214
  }
145
215
 
@@ -400,6 +470,44 @@ declare class DynamicScriptSkill implements Skill {
400
470
  execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
401
471
  }
402
472
 
473
+ interface X402ProxySkillParams {
474
+ name: string;
475
+ description: string;
476
+ capabilities: string[];
477
+ priceSubunits: bigint;
478
+ asset: Asset;
479
+ x402: X402SkillParams;
480
+ image?: string;
481
+ imageFile?: string;
482
+ }
483
+ /**
484
+ * Bridges a job to an x402-paid HTTP upstream. The skill itself is a thin
485
+ * adapter: the whole protocol (payment signing, requirement policies,
486
+ * idempotency cache, error classification) lives in the host-injected
487
+ * `SkillContext.x402` driver, mirroring how `mode: 'llm'` delegates to
488
+ * `ctx.getLlm`. Constructing this skill is gated at load time
489
+ * (`LoadSkillsOptions.allowX402Skills`), so an SDK-only host never
490
+ * advertises a capability it cannot execute.
491
+ */
492
+ declare class X402ProxySkill implements Skill {
493
+ name: string;
494
+ description: string;
495
+ capabilities: string[];
496
+ priceSubunits: bigint;
497
+ asset: Asset;
498
+ mode: SkillMode;
499
+ image?: string;
500
+ imageFile?: string;
501
+ llmOverride?: SkillLlmOverride;
502
+ readonly x402: X402SkillParams;
503
+ constructor(params: X402ProxySkillParams);
504
+ /** GET upstream without a query param consumes no buyer input (card should be static). */
505
+ get noInput(): boolean;
506
+ private requireInvoker;
507
+ preflight(input: SkillInput, ctx: SkillContext): Promise<void>;
508
+ execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
509
+ }
510
+
403
511
  /**
404
512
  * Resolve `value` relative to `rootDir` and reject anything that escapes
405
513
  * the root (`..` segments, absolute paths outside it, or the root itself).
@@ -410,6 +518,14 @@ declare class DynamicScriptSkill implements Skill {
410
518
  declare function resolveInsidePath(rootDir: string, value: string): string | null;
411
519
 
412
520
  declare const DEFAULT_MAX_TOOL_ROUNDS = 10;
521
+ /**
522
+ * Default ceiling on buyer input size for x402 skills (bytes). Conservative:
523
+ * upstream request-body limits are opaque (express.json defaults to 100KB,
524
+ * nginx to 1MiB) and an over-limit POST fails only AFTER the customer paid.
525
+ * Operators raise it per skill via `x402_max_input_bytes` when the upstream
526
+ * is known to accept more; hard cap is `LIMITS.MAX_REINLINE_TEXT_BYTES`.
527
+ */
528
+ declare const DEFAULT_X402_MAX_INPUT_BYTES = 100000;
413
529
  interface SkillFrontmatter {
414
530
  name?: unknown;
415
531
  description?: unknown;
@@ -459,10 +575,11 @@ interface SkillFrontmatter {
459
575
  */
460
576
  input_mime?: unknown;
461
577
  /**
462
- * Whether the skill ALSO accepts a text prompt alongside a file input
463
- * (`dynamic-script` only; meaningful only with `input_mime`). `'none'` = file
464
- * only, `'optional'` = file + optional note (default), `'required'` = needs both.
465
- * Discovery hint only; lets the web app show/hide its text box for file jobs.
578
+ * How the skill treats a text prompt alongside a file input (`dynamic-script`
579
+ * only; meaningful only with `input_mime`). `'none'` = file only, `'optional'` =
580
+ * file optional + instruction required (a generate-or-edit skill), `'required'` =
581
+ * needs both. Omitted = file required + optional note. Discovery hint only; lets
582
+ * the web app show/hide/gate its text box and file picker for file jobs.
466
583
  */
467
584
  input_text?: unknown;
468
585
  /**
@@ -477,6 +594,23 @@ interface SkillFrontmatter {
477
594
  * `execution_timeout_secs`, then to unlimited.
478
595
  */
479
596
  max_execution_secs?: unknown;
597
+ /** Required when mode === 'x402'. Upstream resource URL (https only). */
598
+ x402_url?: unknown;
599
+ /** HTTP method for the upstream call ('GET' | 'POST'). Default 'POST'. x402 mode only. */
600
+ x402_method?: unknown;
601
+ /** Query parameter carrying the buyer input. GET upstreams only; absent => skill takes no input. */
602
+ x402_query_param?: unknown;
603
+ /**
604
+ * Required when mode === 'x402'. Ceiling on the upstream quote in integer
605
+ * subunits of the upstream asset (recorded at `elisym x402 add` time). The
606
+ * host's payment layer refuses to sign anything above it.
607
+ */
608
+ x402_max_upstream?: unknown;
609
+ /**
610
+ * Ceiling on buyer input size in bytes (x402 mode only). Default
611
+ * `DEFAULT_X402_MAX_INPUT_BYTES`; hard cap `LIMITS.MAX_REINLINE_TEXT_BYTES`.
612
+ */
613
+ x402_max_input_bytes?: unknown;
480
614
  }
481
615
  interface ParsedSkill {
482
616
  name: string;
@@ -518,9 +652,10 @@ interface ParsedSkill {
518
652
  */
519
653
  inputMime?: string;
520
654
  /**
521
- * Whether the skill also accepts a text prompt with a file input (mode
522
- * 'dynamic-script' only). Discovery hint; clients (the web app) gate their text
523
- * box on it. Default behavior when absent = file + optional text.
655
+ * How the skill treats a text prompt with a file input (mode 'dynamic-script'
656
+ * only). `'none'` = file only, `'optional'` = file optional + instruction
657
+ * required, `'required'` = both required. Discovery hint; clients (the web app)
658
+ * gate their text box and file picker on it. Absent = file required + optional text.
524
659
  */
525
660
  inputText?: 'required' | 'optional' | 'none';
526
661
  /** Optional per-skill rate limit (any mode). */
@@ -531,6 +666,14 @@ interface ParsedSkill {
531
666
  * then to unlimited.
532
667
  */
533
668
  executionTimeoutSecs?: number;
669
+ /** Set when mode === 'x402': the parsed `x402_*` frontmatter block. */
670
+ x402?: X402SkillParams;
671
+ /**
672
+ * True when the skill consumes no buyer input (x402 GET without a query
673
+ * param). Hosts mark the discovery card `static` so clients hide the input
674
+ * box instead of silently dropping what the buyer typed.
675
+ */
676
+ noInput?: boolean;
534
677
  }
535
678
  interface LoaderLogger {
536
679
  debug?(obj: Record<string, unknown>, msg?: string): void;
@@ -543,6 +686,14 @@ interface LoadSkillsOptions {
543
686
  * false: paid-only (plugin's historical behaviour).
544
687
  */
545
688
  allowFreeSkills?: boolean;
689
+ /**
690
+ * When true, `mode: 'x402'` skills load. Default false: an x402 skill
691
+ * needs a host runtime that injects `SkillContext.x402` (the elisym CLI);
692
+ * an SDK-only host (e.g. the ElizaOS plugin) must fail at load time -
693
+ * NOT after a customer has paid for a job the skill cannot execute.
694
+ * `loadSkillsFromDir` then skips the skill with a warning.
695
+ */
696
+ allowX402Skills?: boolean;
546
697
  logger?: LoaderLogger;
547
698
  }
548
699
  declare function parseSkillMd(content: string): {
@@ -557,4 +708,4 @@ declare function validateSkillFrontmatter(frontmatter: SkillFrontmatter, systemP
557
708
  */
558
709
  declare function loadSkillsFromDir(skillsDir: string, options?: LoadSkillsOptions): Skill[];
559
710
 
560
- 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 };
711
+ 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 CHANGED
@@ -65,6 +65,12 @@ interface SkillContext {
65
65
  * `llmOverride` (or undefined for the agent default).
66
66
  */
67
67
  getLlm?: (override?: SkillLlmOverride) => LlmClient | undefined;
68
+ /**
69
+ * x402 protocol driver for `mode: 'x402'` skills. Injected by the elisym
70
+ * CLI runtime; absent in SDK-only hosts (which also refuse to LOAD x402
71
+ * skills - see `LoadSkillsOptions.allowX402Skills`).
72
+ */
73
+ x402?: X402Invoker;
68
74
  agentName: string;
69
75
  agentDescription: string;
70
76
  signal?: AbortSignal;
@@ -75,10 +81,66 @@ interface SkillContext {
75
81
  * - `static-file`: return the contents of a fixed file. No input required.
76
82
  * - `static-script`: spawn a script with no stdin. No input required.
77
83
  * - `dynamic-script`: spawn a script and pipe the user's input to stdin.
84
+ * - `x402`: proxy the job to an x402-paid HTTP upstream; the host runtime pays
85
+ * the upstream from the agent's wallet. Requires an x402-capable host (the
86
+ * elisym CLI) that injects `SkillContext.x402` - gated at load time via
87
+ * `LoadSkillsOptions.allowX402Skills`.
78
88
  *
79
- * Static modes set `card.static = true` so the webapp hides its input box.
89
+ * Static modes (and an x402 GET skill without a query param) set
90
+ * `card.static = true` so the webapp hides its input box.
91
+ */
92
+ type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script' | 'x402';
93
+ /**
94
+ * Static configuration of an x402 bridge skill, parsed from SKILL.md
95
+ * frontmatter (`x402_*` fields). All money values are integer subunits.
80
96
  */
81
- type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script';
97
+ interface X402SkillParams {
98
+ /** Upstream resource URL (https only). */
99
+ url: string;
100
+ /** HTTP method for the upstream call. Buyer input maps to the POST body or a GET query param. */
101
+ method: 'GET' | 'POST';
102
+ /** Query parameter carrying the buyer input (GET only). Absent on GET => the skill takes no input. */
103
+ queryParam?: string;
104
+ /**
105
+ * Ceiling on the upstream quote in subunits of the upstream asset. The
106
+ * host's payment layer must refuse to sign anything above it - this is the
107
+ * operator's wallet protection against upstream repricing.
108
+ */
109
+ maxUpstreamSubunits: bigint;
110
+ /**
111
+ * Ceiling on the buyer input size in bytes (inline UTF-8 length, or an
112
+ * attachment's declared size). Enforced by the host BEFORE the customer
113
+ * pays - upstream request-body limits are opaque, so an oversized input
114
+ * would otherwise fail deterministically after payment.
115
+ */
116
+ maxInputBytes: number;
117
+ }
118
+ /** Upstream response mapped by Content-Type: text inline, anything else as a file. */
119
+ interface X402ProxyResult {
120
+ data: string;
121
+ outputMime?: string;
122
+ /**
123
+ * Set for a non-text upstream body. The file is owned by the host's
124
+ * idempotency cache (delivery source for crash recovery) - the skill must
125
+ * NOT attach a cleanup callback for it; the cache's TTL sweep deletes it.
126
+ */
127
+ filePath?: string;
128
+ }
129
+ /**
130
+ * Host-provided x402 protocol driver. Implemented by the elisym CLI runtime
131
+ * (payment signing, requirement policies, idempotency, error classification
132
+ * all live host-side); the SDK's `X402ProxySkill` only delegates to it.
133
+ */
134
+ interface X402Invoker {
135
+ /**
136
+ * Pre-payment gate: verify the wallet invariant, probe the live 402 quote
137
+ * against `maxUpstreamSubunits`, check balance/margin and the input-size
138
+ * rules. Throws to refuse the job before the customer pays.
139
+ */
140
+ preflight(params: X402SkillParams, input: SkillInput): Promise<void>;
141
+ /** Perform the paid upstream call (or return a cached result for this jobId). */
142
+ execute(params: X402SkillParams, input: SkillInput, signal?: AbortSignal): Promise<X402ProxyResult>;
143
+ }
82
144
  interface ToolDef {
83
145
  name: string;
84
146
  description: string;
@@ -140,6 +202,14 @@ interface Skill {
140
202
  llmOverride?: SkillLlmOverride;
141
203
  image?: string;
142
204
  imageFile?: string;
205
+ /**
206
+ * Optional pre-payment gate. The runtime calls it BEFORE the customer pays
207
+ * (and before the job enters the ledger); throwing refuses the job with an
208
+ * error feedback and no payment. `input` is the pre-payment view: inline
209
+ * text, tags and jobId only - a file input is fetched after payment, so
210
+ * `filePath` is never set here.
211
+ */
212
+ preflight?(input: SkillInput, ctx: SkillContext): Promise<void>;
143
213
  execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
144
214
  }
145
215
 
@@ -400,6 +470,44 @@ declare class DynamicScriptSkill implements Skill {
400
470
  execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
401
471
  }
402
472
 
473
+ interface X402ProxySkillParams {
474
+ name: string;
475
+ description: string;
476
+ capabilities: string[];
477
+ priceSubunits: bigint;
478
+ asset: Asset;
479
+ x402: X402SkillParams;
480
+ image?: string;
481
+ imageFile?: string;
482
+ }
483
+ /**
484
+ * Bridges a job to an x402-paid HTTP upstream. The skill itself is a thin
485
+ * adapter: the whole protocol (payment signing, requirement policies,
486
+ * idempotency cache, error classification) lives in the host-injected
487
+ * `SkillContext.x402` driver, mirroring how `mode: 'llm'` delegates to
488
+ * `ctx.getLlm`. Constructing this skill is gated at load time
489
+ * (`LoadSkillsOptions.allowX402Skills`), so an SDK-only host never
490
+ * advertises a capability it cannot execute.
491
+ */
492
+ declare class X402ProxySkill implements Skill {
493
+ name: string;
494
+ description: string;
495
+ capabilities: string[];
496
+ priceSubunits: bigint;
497
+ asset: Asset;
498
+ mode: SkillMode;
499
+ image?: string;
500
+ imageFile?: string;
501
+ llmOverride?: SkillLlmOverride;
502
+ readonly x402: X402SkillParams;
503
+ constructor(params: X402ProxySkillParams);
504
+ /** GET upstream without a query param consumes no buyer input (card should be static). */
505
+ get noInput(): boolean;
506
+ private requireInvoker;
507
+ preflight(input: SkillInput, ctx: SkillContext): Promise<void>;
508
+ execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
509
+ }
510
+
403
511
  /**
404
512
  * Resolve `value` relative to `rootDir` and reject anything that escapes
405
513
  * the root (`..` segments, absolute paths outside it, or the root itself).
@@ -410,6 +518,14 @@ declare class DynamicScriptSkill implements Skill {
410
518
  declare function resolveInsidePath(rootDir: string, value: string): string | null;
411
519
 
412
520
  declare const DEFAULT_MAX_TOOL_ROUNDS = 10;
521
+ /**
522
+ * Default ceiling on buyer input size for x402 skills (bytes). Conservative:
523
+ * upstream request-body limits are opaque (express.json defaults to 100KB,
524
+ * nginx to 1MiB) and an over-limit POST fails only AFTER the customer paid.
525
+ * Operators raise it per skill via `x402_max_input_bytes` when the upstream
526
+ * is known to accept more; hard cap is `LIMITS.MAX_REINLINE_TEXT_BYTES`.
527
+ */
528
+ declare const DEFAULT_X402_MAX_INPUT_BYTES = 100000;
413
529
  interface SkillFrontmatter {
414
530
  name?: unknown;
415
531
  description?: unknown;
@@ -459,10 +575,11 @@ interface SkillFrontmatter {
459
575
  */
460
576
  input_mime?: unknown;
461
577
  /**
462
- * Whether the skill ALSO accepts a text prompt alongside a file input
463
- * (`dynamic-script` only; meaningful only with `input_mime`). `'none'` = file
464
- * only, `'optional'` = file + optional note (default), `'required'` = needs both.
465
- * Discovery hint only; lets the web app show/hide its text box for file jobs.
578
+ * How the skill treats a text prompt alongside a file input (`dynamic-script`
579
+ * only; meaningful only with `input_mime`). `'none'` = file only, `'optional'` =
580
+ * file optional + instruction required (a generate-or-edit skill), `'required'` =
581
+ * needs both. Omitted = file required + optional note. Discovery hint only; lets
582
+ * the web app show/hide/gate its text box and file picker for file jobs.
466
583
  */
467
584
  input_text?: unknown;
468
585
  /**
@@ -477,6 +594,23 @@ interface SkillFrontmatter {
477
594
  * `execution_timeout_secs`, then to unlimited.
478
595
  */
479
596
  max_execution_secs?: unknown;
597
+ /** Required when mode === 'x402'. Upstream resource URL (https only). */
598
+ x402_url?: unknown;
599
+ /** HTTP method for the upstream call ('GET' | 'POST'). Default 'POST'. x402 mode only. */
600
+ x402_method?: unknown;
601
+ /** Query parameter carrying the buyer input. GET upstreams only; absent => skill takes no input. */
602
+ x402_query_param?: unknown;
603
+ /**
604
+ * Required when mode === 'x402'. Ceiling on the upstream quote in integer
605
+ * subunits of the upstream asset (recorded at `elisym x402 add` time). The
606
+ * host's payment layer refuses to sign anything above it.
607
+ */
608
+ x402_max_upstream?: unknown;
609
+ /**
610
+ * Ceiling on buyer input size in bytes (x402 mode only). Default
611
+ * `DEFAULT_X402_MAX_INPUT_BYTES`; hard cap `LIMITS.MAX_REINLINE_TEXT_BYTES`.
612
+ */
613
+ x402_max_input_bytes?: unknown;
480
614
  }
481
615
  interface ParsedSkill {
482
616
  name: string;
@@ -518,9 +652,10 @@ interface ParsedSkill {
518
652
  */
519
653
  inputMime?: string;
520
654
  /**
521
- * Whether the skill also accepts a text prompt with a file input (mode
522
- * 'dynamic-script' only). Discovery hint; clients (the web app) gate their text
523
- * box on it. Default behavior when absent = file + optional text.
655
+ * How the skill treats a text prompt with a file input (mode 'dynamic-script'
656
+ * only). `'none'` = file only, `'optional'` = file optional + instruction
657
+ * required, `'required'` = both required. Discovery hint; clients (the web app)
658
+ * gate their text box and file picker on it. Absent = file required + optional text.
524
659
  */
525
660
  inputText?: 'required' | 'optional' | 'none';
526
661
  /** Optional per-skill rate limit (any mode). */
@@ -531,6 +666,14 @@ interface ParsedSkill {
531
666
  * then to unlimited.
532
667
  */
533
668
  executionTimeoutSecs?: number;
669
+ /** Set when mode === 'x402': the parsed `x402_*` frontmatter block. */
670
+ x402?: X402SkillParams;
671
+ /**
672
+ * True when the skill consumes no buyer input (x402 GET without a query
673
+ * param). Hosts mark the discovery card `static` so clients hide the input
674
+ * box instead of silently dropping what the buyer typed.
675
+ */
676
+ noInput?: boolean;
534
677
  }
535
678
  interface LoaderLogger {
536
679
  debug?(obj: Record<string, unknown>, msg?: string): void;
@@ -543,6 +686,14 @@ interface LoadSkillsOptions {
543
686
  * false: paid-only (plugin's historical behaviour).
544
687
  */
545
688
  allowFreeSkills?: boolean;
689
+ /**
690
+ * When true, `mode: 'x402'` skills load. Default false: an x402 skill
691
+ * needs a host runtime that injects `SkillContext.x402` (the elisym CLI);
692
+ * an SDK-only host (e.g. the ElizaOS plugin) must fail at load time -
693
+ * NOT after a customer has paid for a job the skill cannot execute.
694
+ * `loadSkillsFromDir` then skips the skill with a warning.
695
+ */
696
+ allowX402Skills?: boolean;
546
697
  logger?: LoaderLogger;
547
698
  }
548
699
  declare function parseSkillMd(content: string): {
@@ -557,4 +708,4 @@ declare function validateSkillFrontmatter(frontmatter: SkillFrontmatter, systemP
557
708
  */
558
709
  declare function loadSkillsFromDir(skillsDir: string, options?: LoadSkillsOptions): Skill[];
559
710
 
560
- 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 };
711
+ 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 };