@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/agent-store.cjs +16 -4
- package/dist/agent-store.cjs.map +1 -1
- package/dist/agent-store.d.cts +11 -4
- package/dist/agent-store.d.ts +11 -4
- package/dist/agent-store.js +17 -6
- package/dist/agent-store.js.map +1 -1
- package/dist/index.cjs +30 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +28 -9
- package/dist/index.d.ts +28 -9
- package/dist/index.js +28 -2
- package/dist/index.js.map +1 -1
- package/dist/node.cjs.map +1 -1
- package/dist/node.js.map +1 -1
- package/dist/skills.cjs +190 -2
- package/dist/skills.cjs.map +1 -1
- package/dist/skills.d.cts +161 -10
- package/dist/skills.d.ts +161 -10
- package/dist/skills.js +189 -3
- package/dist/skills.js.map +1 -1
- package/package.json +1 -1
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
|
|
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
|
-
|
|
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
|
-
*
|
|
463
|
-
*
|
|
464
|
-
*
|
|
465
|
-
*
|
|
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
|
-
*
|
|
522
|
-
*
|
|
523
|
-
*
|
|
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
|
|
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
|
-
|
|
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
|
-
*
|
|
463
|
-
*
|
|
464
|
-
*
|
|
465
|
-
*
|
|
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
|
-
*
|
|
522
|
-
*
|
|
523
|
-
*
|
|
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 };
|