Sanitization

The plugin treats free-form text fields (identity name/description, knowledge source descriptions, prefetched memory) as untrusted. It wraps them in a <external-data> envelope with a preamble, caps them at 2KB with a truncation marker, and strips C0 controls, ANSI escapes, zero-width characters, and bidi-override Unicode characters. Numeric IDs, addresses, on-chain enums, and structural keys are not wrapped. This sanitization raises the bar from trivial injection but is not a complete defense; the operator-key boundary is the primary security measure.

Failure Modes

• Operator key not set or invalid: writes disabled or fail.
• Operator key not funded: gas insufficient for writes.
• Policy file missing or malformed: writes blocked.
• BORT_ALLOW_BROADCAST unset: writes simulate only, no real broadcast.
• Pinata credentials missing: anchor tools return a clear error.
• Self-evolution repository not found: evolve command fails.
• Agent owner has not granted operator permission: writes fail.
• CircuitBreaker paused (global or per-contract): write preflight fails.
• VPMv2.canForward returns false: writes blocked.
• Policy disposition blocks action: writes blocked.
• Hermes approval prompt declined (for confirm dispositions): writes cancelled.
• IPFS pinning fails: commit_evolution or anchor_memory fails.
• On-chain write fails (e.g., revert, gas): transaction not broadcast or fails.
• Memory file not found: anchor_memory fails.
• Network unreachable: reads and writes fail.

Constraints and Caveats

• The operator key is never written to disk by the plugin; it is printed once to stdout for the user to set in the environment.
• The operator can only do what the owner has granted in VaultPermissionManagerV2 and what the policy file allows.
• A leaked operator key can be revoked by the owner with one revokePermission transaction. The operator cannot mint, transfer, or list the NFT.
• commit_evolution needs Pinata credentials; commit_learning does not (it only emits a content hash).
• The plugin includes 99 tests, most integration-style hitting BSC mainnet RPC and the BORT runtime API. Network tests are skipped when the relevant environment variable is unset.

Examples

Read an agent: use bort_read_agent with token_id=11100 to print the owner and logic name/snapshot.

Browse marketplace: use bort_marketplace_browse with sort='price_asc', limit=10 to print listings with token_id, price_per_token, and lister.

Drive an action through operator: after granting permission, use bort_invoke with token_id=11100, action='buy_token', and args including token_address and amount_bnb_wei. The response shows status (broadcast, simulated_only, or blocked) and tx_hash.

Anchor session memory to IPFS: run hermes bort anchor-memory --token-id 11100 after the owner grants WRITE permission.

Generate marketplace deep link: use bort_list_agent_uri with token_id=11100 and intent='list' to get a URL like https://www.bortagent.xyz/#/my-listings.

Detailed Tool Reference

bort_read_agent

This tool fetches the complete on-chain state of a BORT agent NFT. It returns the owner address, logic contract name and snapshot, IPFS identity, and any knowledge registries associated with the token. The tool requires a single parameter token_id as an integer. The response is a JSON string that can be parsed and inspected. The tool connects to the BORT runtime API and BSC RPC to gather this data. If the token ID does not exist on-chain, the tool returns an error indicating the token was not found.

bort_health_check

This tool verifies connectivity to the BORT runtime API and BSC RPC. It returns a status message indicating whether both endpoints are reachable. Use this tool before any other operations to confirm network access. The tool takes no parameters.

bort_list_actions

This tool lists all available on-chain actions for a specific BORT agent. It requires a token_id parameter. The response includes action names and their expected arguments. This is useful for determining what actions can be passed to bort_invoke. The tool queries the agent's logic contract through the runtime API.

bort_marketplace_browse

This tool browses the BORT marketplace for agent listings. It accepts optional parameters sort (default price_asc) and limit (default 10). The response prints a table of listings with columns for token_id, price_per_token, and lister address. The tool connects to the BORT marketplace contract on BSC. If no listings are found, the tool returns an empty list.

bort_marketplace_agent

This tool retrieves marketplace details for a specific agent. It requires a token_id parameter. The response includes the listing price, lister address, and any other marketplace metadata. The tool queries the marketplace contract directly.

bort_list_agent_uri

This tool generates a deep link URL for the BORT dapp. It requires token_id and intent parameters. The intent parameter can be list or unlist. The returned URL can be opened in a browser to perform the corresponding marketplace action. The tool constructs the URL using the BORT_DAPP_URL environment variable.

bort_grant_permission_uri

This tool generates a URI that the agent owner can use to grant operator permission. It requires token_id and operator address parameters. The returned URI contains calldata for the two-step process (createVault then grantPermission). The owner must sign and submit this calldata to the blockchain. The tool does not submit the transaction itself.

bort_commit_learning

This tool commits a learning record on-chain for a BORT agent. It requires token_id and a content_hash parameter (a string representing the IPFS content hash of the learning data). The tool emits a LearningRecorded event on the agent's logic contract. This tool does not require Pinata credentials because it only emits a hash, not pinning data. The operator must have WRITE permission from the agent owner.

bort_invoke

This tool executes an on-chain action via the VaultPermissionManagerV2 contract. It requires token_id, action (a string matching an action from bort_list_actions), and args (a dictionary of action-specific parameters). The tool performs write preflight checks before execution. The response includes status which is one of broadcast, simulated_only, or blocked. If broadcast, the response also includes tx_hash. The tool respects the BORT_ALLOW_BROADCAST environment variable.

bort_anchor_memory

This tool anchors local session memory to IPFS and KnowledgeRegistryV2. It requires token_id as a parameter. The tool reads the local JSONL buffer from BORT_MEMORY_DIR, pins it to IPFS via Pinata, and commits it as a MEMORY knowledge source on-chain. The tool requires Pinata credentials to be set. If the memory file does not exist, the tool returns an error.

bort_commit_evolution

This tool commits an evolved skill and learning record on-chain. It requires token_id and a skill_content_hash parameter. The tool pins the evolved skill to IPFS and writes it as an INSTRUCTION knowledge source on KnowledgeRegistryV2. It also emits a LearningRecorded event. This tool requires Pinata credentials for the IPFS pinning step. The operator must have WRITE permission.

Policy File Format

The policy file is a YAML file located at BORT_POLICY_PATH (default ~/.hermes/bort-policy.yaml). Each action has a disposition and an optional per_action_max_bnb cap. The disposition can be auto (allow without prompt), confirm (prompt user for approval), or block (deny the action). The per_action_max_bnb cap limits the maximum BNB value for that action in wei. Example policy:

actions:
  buy_token:
    disposition: auto
    per_action_max_bnb: 100000000000000000
  sell_token:
    disposition: confirm
  transfer:
    disposition: block

If an action is not listed in the policy, the default disposition is block.

Operator Key Management

The operator key is generated with hermes bort init-operator. The plugin prints the private key and address to stdout once. The user must set BORT_OPERATOR_PRIVATE_KEY in the environment. The plugin never writes the private key to disk. The operator address must be funded with approximately 0.01 BNB for gas. The operator can only perform actions that the agent owner has granted in VaultPermissionManagerV2 and that the policy file allows. The owner can revoke operator permission at any time with a single revokePermission transaction. The operator cannot mint, transfer, or list the NFT.

Granting Operator Permission

The agent owner must grant operator permission through a two-step process. First, a vault is created for the agent. Second, the operator is granted permission on that vault. The bort_grant_permission_uri tool generates the calldata for both steps. The owner must sign and submit this calldata to the blockchain. The plugin does not submit the transaction. The permission grant is specific to a token ID and operator address. The owner can specify which actions the operator is allowed to perform.

Testing

The plugin includes 99 tests, most integration-style hitting BSC mainnet RPC and the BORT runtime API. Network tests are skipped when the relevant environment variable is unset. The BORT_TEST_TOKEN_ID environment variable specifies which token ID to use for testing. Tests cover read tools, write tools, memory portability, and evolve functionality. To run tests, use pytest from the plugin directory.

Troubleshooting

If writes fail, check the following in order:

1. Run hermes bort doctor to verify setup.
2. Confirm BORT_OPERATOR_PRIVATE_KEY is set correctly.
3. Verify the operator address has sufficient BNB for gas.
4. Check the policy file exists and is valid YAML.
5. Confirm the agent owner has granted operator permission.
6. Set BORT_ALLOW_BROADCAST=1 if you want real broadcasts.
7. Check network connectivity to BSC RPC and BORT API.

If memory anchoring fails, verify PINATA_API_KEY and PINATA_API_SECRET are set. If evolve fails, confirm the hermes-agent-self-evolution repository is present and the LLM API keys are set in the environment.