Enum ToolsetFormatError 

pub enum ToolsetFormatError {
    Io {
        detail: String,
    },
    ToolsetFileTooLarge {
        size: u64,
        cap: u64,
    },
    NotUtf8,
    MissingFrontmatter,
    MalformedFrontmatter {
        detail: String,
    },
    YamlAnchorsForbidden,
    FrontmatterTooDeep,
    DuplicateKey {
        key: String,
    },
    ReservedMetadataKey {
        key: String,
    },
    MissingName,
    NameEmpty,
    NameTooLong,
    NameInvalidChar,
    NameLeadingTrailingHyphen,
    NameConsecutiveHyphens,
    NameDirMismatch {
        name: String,
        dir: String,
    },
    MissingDescription,
    DescriptionEmpty,
    DescriptionTooLong,
    CompatibilityTooLong,
    CapabilityTokenInvalidChar {
        token: String,
    },
    UnknownCapability {
        token: String,
    },
    BareSignTransactionForbidden,
    CapabilityManifestMalformed {
        detail: String,
    },
}

All distinct reasons a toolset directory can be refused by crate::parse_toolset.

The set is closed: a match on ToolsetFormatError that is exhaustive today will require an update if new variants are added. The #[non_exhaustive] attribute is intentionally absent — the parity test in this module locks the surface by failing to compile when a variant is added without updating the test.

Variants

Io

The TOOLSET.md file could not be read from the toolset directory.

The detail string is the sanitised I/O error message; it never contains attacker-controlled path contents longer than ECHO_CAP bytes.

Fields

detail: String

Sanitised I/O error description.

ToolsetFileTooLarge

The TOOLSET.md file exceeds the 256 KiB size cap (enforced before parsing).

Fields

size: u64

Actual file size in bytes.

cap: u64

Maximum permitted size in bytes.

NotUtf8

The TOOLSET.md bytes are not valid UTF-8.

MissingFrontmatter

The file does not begin with a --- YAML frontmatter fence.

MalformedFrontmatter

The YAML inside the frontmatter fence could not be parsed.

detail is the parser’s error message (not a file-content snippet).

Fields

detail: String

Parser error description.

YamlAnchorsForbidden

The frontmatter YAML contains an anchor (&a) or alias (*a).

Anchors and aliases are forbidden to prevent alias-expansion DoS (billion-laughs attack class). The parser rejects them before any tree is materialised.

FrontmatterTooDeep

The frontmatter nesting depth exceeds the limit of 8.

Deeply-nested input is refused before full materialisation to prevent stack-overflow or runaway recursion during mapping.

DuplicateKey

A mapping key appears more than once in the frontmatter (at the top level or inside the metadata block).

Duplicate keys are a common confusion vector: a human reviewer sees one value while a parser resolves another. We refuse rather than silently resolving to first-wins or last-wins.

Fields

key: String

The key that appeared more than once.

ReservedMetadataKey

A metadata key begins with the reserved prefix stellar-agent- but is not a recognised wallet key.

Currently the only recognised wallet-reserved key is stellar-agent-capabilities. Any other stellar-agent--prefixed key is refused to prevent future collision with wallet-defined extensions.

Fields

key: String

The offending metadata key.

MissingName

The name field is absent from the frontmatter.

NameEmpty

The name field is present but empty.

NameTooLong

The name field exceeds 64 characters.

NameInvalidChar

The name field contains a character outside [a-z0-9-].

The agentskills spec’s “unicode lowercase alphanumeric” wording is resolved in favour of the ASCII range it explicitly enumerates (a-z, 0-9). Non-ASCII characters — including unicode homoglyphs of ASCII letters — are refused here rather than silently normalised.

NameLeadingTrailingHyphen

The name field starts or ends with a hyphen.

NameConsecutiveHyphens

The name field contains consecutive hyphens (--).

NameDirMismatch

The name field does not match the parent directory name (byte-exact).

Because name is constrained to ASCII [a-z0-9-] and the comparison is byte-exact, a unicode-homoglyph directory name (e.g. containing Cyrillic look-alikes) always fails here rather than matching by visual equivalence.

Fields

name: String

The name value from the frontmatter.

dir: String

The actual directory name the toolset was loaded from.

MissingDescription

The description field is absent from the frontmatter.

DescriptionEmpty

The description field is present but empty (or whitespace-only).

DescriptionTooLong

The description field exceeds 1024 characters.

CompatibilityTooLong

The compatibility field (if present) exceeds 500 characters.

CapabilityTokenInvalidChar

A capability token contains a character outside [a-z0-9-].

The charset gate is applied BEFORE name-matching so that no casing variant of a recognised or forbidden token can reach the matching step. Sign-Transaction, SIGN-TRANSACTION, sign_transaction, a tab-padded token, or a unicode-homoglyph are each refused here.

Fields

token: String

The offending token (sanitised, length-capped).

UnknownCapability

A capability token passed the charset gate but is not in the recognised taxonomy.

Unknown tokens are refused rather than silently ignored so that a toolset author’s typo (reed-balance) does not silently produce an empty capability set.

Fields

token: String

The unrecognised token (sanitised, length-capped).

BareSignTransactionForbidden

The token sign-transaction was found in the capability manifest.

Signing is not grantable as a flat capability declaration. Toolsets may not declare sign-transaction; the signing path is governed by the first-invoke gate and the attestation gate.

This is a distinct error from ToolsetFormatError::UnknownCapability to make the “no bare sign” rule legible: an author who writes sign-transaction gets a clear explanation rather than a generic “unknown token” message.

CapabilityManifestMalformed

The stellar-agent-capabilities metadata value is not a YAML string.

The agentskills spec defines metadata values as strings; a YAML list or mapping value is a spec violation and is refused.

Fields

detail: String

Description of the malformation.

Trait Implementations

impl Debug for ToolsetFormatError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ToolsetFormatError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for ToolsetFormatError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.