Enum ToolsetRuntimeError 

#[non_exhaustive]
pub enum ToolsetRuntimeError {
    UnknownToolsetAction {
        action: String,
    },
    CapabilityNotDeclared {
        action: String,
        capability: String,
    },
    ToolNotAllowed {
        tool: String,
        action: String,
    },
    ToolsetNotInstalled {
        name: String,
    },
    Io(String),
    ContentDigestMismatch {
        name: String,
    },
    FirstInvokeApprovalRequired {
        approval_nonce: String,
        toolset_name: String,
        capability: String,
    },
    GrantStoreError {
        detail: String,
    },
    InvalidAuthoritativeAmount {
        amount_stroops: i64,
    },
}

Typed refusal errors for toolset capability enforcement.

Closed set: one variant per failure mode in the four-part check. All author-controlled string fields are pre-sanitised by callers via stellar_agent_toolsets::sanitise_display before being stored here.

Variants

Variant	Four-part step	Description
ToolsetRuntimeError::UnknownToolsetAction	(a)	Action not in matrix.
ToolsetRuntimeError::CapabilityNotDeclared	(c)	Granting capability not in toolset’s CapabilitySet.
ToolsetRuntimeError::ToolNotAllowed	(d)	Tool excluded by toolset’s allowed_tools narrowing.
ToolsetRuntimeError::ToolsetNotInstalled	pre-check	Toolset name has no pin record.
ToolsetRuntimeError::Io	pre-check	I/O error reading the pin.
ToolsetRuntimeError::ContentDigestMismatch	pre-check	On-disk TOOLSET.md hash differs from install-time digest.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

UnknownToolsetAction

Part (a): the action name is not in the capability→tool matrix.

The action is either a signing/key/policy tool (explicitly excluded), a dispatcher tool (stellar_toolset_list / stellar_toolset_invoke), or simply not a recognised wallet tool name.

Security note

This variant fires before any capability check — a toolset cannot probe whether a signing tool “would be allowed” by its capabilities.

Fields

action: String

Sanitised action name from the invocation request.

CapabilityNotDeclared

Part (c): the action’s granting capability is not in the toolset’s declared stellar_agent_toolsets::CapabilitySet.

The toolset would need to declare the named capability to invoke this action.

Fields

action: String

Sanitised action name.

capability: String

Display token of the required capability (e.g. "read-balance").

ToolNotAllowed

Part (d): the resolved tool is not in the toolset’s allowed_tools list.

The toolset’s allowed_tools narrows the capability grant — it can only subtract, never add. The tool is grantable by the toolset’s declared capabilities but has been excluded by the intersective narrowing.

Fields

tool: String

Sanitised registry tool name.

action: String

Sanitised action name.

ToolsetNotInstalled

Pre-check: the toolset name has no pin record in the toolsets directory.

The toolset is not installed, or has been uninstalled since the invocation was queued.

Fields

name: String

Sanitised toolset package name.

Io(String)

Pre-check: an I/O error occurred while reading the pin record.

ContentDigestMismatch

Pre-check: the on-disk TOOLSET.md SHA-256 digest does not match the digest recorded in the pin at install time.

Fires when the pin’s toolset_md_shasum field is Some and the current file’s hash differs. This indicates post-install modification of the manifest file.

Recovery

Reinstall the toolset from the signed package:

stellar-agent toolset install <package> --force

Security note

The capability-source invariant (capabilities are read from the pin, never re-parsed from the on-disk TOOLSET.md) ensures that a tampered manifest CANNOT escalate capabilities even before this check fires. This check adds tamper-evidence for the manifest text and refuses dispatch to surface the incident rather than silently continuing with stale metadata.

Fields

name: String

Sanitised toolset package name.

FirstInvokeApprovalRequired

Gated path: the first-invoke gate requires out-of-band approval.

The gated resolver (resolve_toolset_sign_payment_gated) returns Ok(GatedResolveOutcome::FirstInvokeApprovalRequired { .. }) when the gate fires. Production never constructs this error variant; the MCP match arm must fail closed.

Recovery

1. The operator reviews the wallet-rendered summary.
2. stellar-agent approve --id <approval_nonce> --profile <name> is run.
3. The toolset re-invokes the same sign-payment action.

Fields

approval_nonce: String

Nonce of the queued ToolsetFirstInvokeGate pending approval.

The MCP response MUST surface this nonce so the agent can pass it to stellar-agent approve --id <nonce> --profile <name>.

toolset_name: String

Sanitised toolset name (for the human-readable message).

capability: String

Capability token (e.g. "sign-payment").

GrantStoreError

Gated path: an I/O error occurred accessing the toolset grant store.

Fields

detail: String

Non-secret diagnostic detail.

InvalidAuthoritativeAmount

Gated path: the authoritative payment amount is not positive.

authoritative_amount_stroops must be greater than zero. A zero or negative value from the decoded envelope is rejected here before any grant-store lookup or approval queuing occurs.

Fields

amount_stroops: i64

The non-positive value that was rejected.

Trait Implementations

impl Debug for ToolsetRuntimeError

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

Formats the value using the given formatter.

impl Display for ToolsetRuntimeError

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

Formats the value using the given formatter.

impl Error for ToolsetRuntimeError

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.