Skip to content

Tools

tools

AXM tools for the vault — vault_doctor, vault_set, vault_delete.

All three tools are deterministic :class:~axm.tools.base.AXMTool implementations so they are reachable over MCP, the axm CLI and as DAG nodes from a single axm.tools entry-point declaration. They uphold the vault's central security invariant: no tool ever serializes a SECRET value. vault_doctor returns value-free provenance; vault_set stores a value but echoes only the storage target, never the value; vault_delete removes a stored credential and reports only the deletion target.

VaultDeleteTool

Remove a stored credential by group.name from the keyring.

The group.name is resolved through the catalog first (validating it is a known spec), then deleted from the OS keyring. Deletion is a safe no-op when the credential is already absent — the underlying store suppresses the keyring's Item not found error — so callers can delete idempotently. Only the deletion target is reported, never a value.

Source code in packages/axm-vault/src/axm_vault/tools.py
Python
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
class VaultDeleteTool:
    """Remove a stored credential by ``group.name`` from the keyring.

    The ``group.name`` is resolved through the catalog first (validating it is
    a known spec), then deleted from the OS keyring. Deletion is a **safe
    no-op** when the credential is already absent — the underlying store
    suppresses the keyring's ``Item not found`` error — so callers can delete
    idempotently. Only the deletion target is reported, never a value.
    """

    agent_hint = (
        "Delete a stored credential from the OS keyring by group.name; it is a "
        "safe no-op when the secret is already absent. No value is returned."
    )
    domain = "vault"
    tags = frozenset({"vault", "credentials", "delete"})

    @property
    def name(self) -> str:
        """Unique tool identifier."""
        return "vault_delete"

    def execute(
        self, *, group: str = "", name: str = "", instance: str | None = None
    ) -> ToolResult:
        """Resolve ``group.name`` then delete it from the keyring (no-op if absent)."""
        try:
            spec = load_catalog().group(group).spec(name)
            KeyringStore().delete(group, spec.name, instance)
        except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
            return ToolResult(success=False, error=str(exc))
        return ToolResult(
            success=True, data={"deleted": f"keyring:{group}.{spec.name}"}
        )
name property

Unique tool identifier.

execute(*, group='', name='', instance=None)

Resolve group.name then delete it from the keyring (no-op if absent).

Source code in packages/axm-vault/src/axm_vault/tools.py
Python
138
139
140
141
142
143
144
145
146
147
148
149
def execute(
    self, *, group: str = "", name: str = "", instance: str | None = None
) -> ToolResult:
    """Resolve ``group.name`` then delete it from the keyring (no-op if absent)."""
    try:
        spec = load_catalog().group(group).spec(name)
        KeyringStore().delete(group, spec.name, instance)
    except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
        return ToolResult(success=False, error=str(exc))
    return ToolResult(
        success=True, data={"deleted": f"keyring:{group}.{spec.name}"}
    )

VaultDoctorTool

Report credential provenance (layer + presence), never a value.

Source code in packages/axm-vault/src/axm_vault/tools.py
Python
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
class VaultDoctorTool:
    """Report credential provenance (layer + presence), never a value."""

    agent_hint = (
        "Report which layer (env/file/keyring/default/missing) supplies each "
        "credential and whether it is present — values are NEVER returned."
    )
    domain = "vault"
    tags = frozenset({"vault", "credentials", "doctor", "provenance"})

    @property
    def name(self) -> str:
        """Unique tool identifier."""
        return "vault_doctor"

    def execute(
        self, *, package: str | None = None, instance: str | None = None
    ) -> ToolResult:
        """Return value-free provenance for the catalog (or one package)."""
        try:
            data = doctor_data(package, instance=instance)
        except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
            return ToolResult(success=False, error=str(exc))
        return ToolResult(success=True, data=dict(data))
name property

Unique tool identifier.

execute(*, package=None, instance=None)

Return value-free provenance for the catalog (or one package).

Source code in packages/axm-vault/src/axm_vault/tools.py
Python
40
41
42
43
44
45
46
47
48
def execute(
    self, *, package: str | None = None, instance: str | None = None
) -> ToolResult:
    """Return value-free provenance for the catalog (or one package)."""
    try:
        data = doctor_data(package, instance=instance)
    except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
        return ToolResult(success=False, error=str(exc))
    return ToolResult(success=True, data=dict(data))

VaultSetTool

Store a credential by group.name — keyring (SECRET) or config.

NONSENSITIVE credentials are environment-only and are rejected outright: storing them would create a second, stale source of truth. The stored value is never echoed back — only the storage target is reported.

Source code in packages/axm-vault/src/axm_vault/tools.py
Python
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class VaultSetTool:
    """Store a credential by ``group.name`` — keyring (SECRET) or config.

    NONSENSITIVE credentials are environment-only and are rejected outright:
    storing them would create a second, stale source of truth. The stored
    value is never echoed back — only the storage target is reported.
    """

    agent_hint = (
        "Store a credential: SECRET -> OS keyring, CONFIG -> axm-config; "
        "NONSENSITIVE is env-only and rejected. The value is never echoed."
    )
    domain = "vault"
    tags = frozenset({"vault", "credentials", "set"})

    @property
    def name(self) -> str:
        """Unique tool identifier."""
        return "vault_set"

    def execute(
        self,
        *,
        group: str,
        name: str,
        value: str,
        instance: str | None = None,
    ) -> ToolResult:
        """Route ``group.name`` to its store by sensitivity; never echo value."""
        try:
            spec = load_catalog().group(group).spec(name)
            target = self._store(spec.sensitivity, group, name, value, instance)
        except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
            return ToolResult(success=False, error=str(exc))
        return ToolResult(success=True, data={"stored": target})

    @staticmethod
    def _store(
        sensitivity: Sensitivity,
        group: str,
        name: str,
        value: str,
        instance: str | None,
    ) -> str:
        """Persist ``value`` to the backend for ``sensitivity``; return target.

        Raises:
            ValueError: when ``sensitivity`` is NONSENSITIVE (env-only).
        """
        target = f"{group}.{name}"
        match sensitivity:
            case Sensitivity.SECRET:
                KeyringStore().set(group, name, value, instance)
                return f"keyring:{target}"
            case Sensitivity.CONFIG:
                axm_config.set_(group, name, value)
                return f"config:{target}"
            case Sensitivity.NONSENSITIVE:
                msg = (
                    f"{target} is NONSENSITIVE (environment-only); "
                    "set it via its env var, it is never stored"
                )
                raise ValueError(msg)
name property

Unique tool identifier.

execute(*, group, name, value, instance=None)

Route group.name to its store by sensitivity; never echo value.

Source code in packages/axm-vault/src/axm_vault/tools.py
Python
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def execute(
    self,
    *,
    group: str,
    name: str,
    value: str,
    instance: str | None = None,
) -> ToolResult:
    """Route ``group.name`` to its store by sensitivity; never echo value."""
    try:
        spec = load_catalog().group(group).spec(name)
        target = self._store(spec.sensitivity, group, name, value, instance)
    except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
        return ToolResult(success=False, error=str(exc))
    return ToolResult(success=True, data={"stored": target})