feat: add Account & Asset Explorer tools with read-only Horizon queries

[efekrbas]

Summary

Adds two new LangChain tools (StellarAccountTool, StellarAssetTool) and their underlying libraries that provide read-only access to Stellar account data and SDEX market information. These tools fill a critical gap in the toolkit — agents can now inspect accounts, check balances, review transaction history, and analyze market data without requiring a private key.

Motivation

The existing toolset covers transactional operations (swap, bridge, stake, LP, claim) but lacks any read-only exploration capability. An agent currently has no way to:

• Check an account's balances or signer configuration
• Review recent transactions or operations
• Look up asset metadata (trust count, supply, issuer flags)
• Inspect the SDEX orderbook or recent trades
• Fund a testnet account via Friendbot
  This PR adds all of the above as a cohesive, well-tested feature.

What's New

StellarAccountTool — 5 actions

Action	Description
get_info	Full account details: balances, signers, thresholds, flags, home domain
get_balances	Quick balance summary (XLM + all trusted assets)
get_transactions	Recent transaction history with memo, fee, and success status
get_operations	Recent operation history with type-specific details
fund_testnet	Fund a testnet account via Stellar Friendbot (testnet only)

StellarAssetTool — 3 actions

Action	Description
get_asset_details	Asset metadata: trust count, circulating supply, issuer flags
get_orderbook	Current SDEX bids/asks for any trading pair
get_trades	Recent trade history for any trading pair

AgentClient Integration

• agent.account.* namespace — getInfo(), getBalances(), getTransactions(), getOperations(), fundTestnet()
• agent.asset.* namespace — getDetails(), getOrderbook(), getTrades()
• All methods default to the configured publicKey and network
• New types exported: AccountInfo, AccountBalance, TransactionRecord, OperationRecord, AssetDetails, OrderbookSummary, TradeRecord

Architecture

lib/account.ts → Core Horizon queries (account, tx, ops, friendbot) lib/asset.ts → Core Horizon queries (assets, orderbook, trades) tools/account.ts → LangChain DynamicStructuredTool wrapper tools/asset.ts → LangChain DynamicStructuredTool wrapper agent.ts → account.* and asset.* namespace integration index.ts → Exports + stellarTools array registration

• Dependency injection (_deps.createServer) for testability without fragile module-level mocks
• Zod schemas for all tool inputs with descriptive field documentation
• Input validation with user-friendly error messages (invalid keys, out-of-range limits, malformed asset codes)
• Both testnet and mainnet supported via network parameter

Test Coverage

Test File	Tests	Coverage
tests/unit/lib/account.test.ts	15	getAccountInfo, getBalances, getTransactionHistory, getOperationHistory, fundTestnetAccount
tests/unit/lib/asset.test.ts	10	getAssetDetails, getOrderbook, getTrades
tests/unit/tools/account.test.ts	8	Tool delegation, edge cases, mainnet guard
tests/unit/tools/asset.test.ts	7	Tool delegation, parameter validation, limit clamping
All 99 tests pass (40 new + 59 existing), zero regressions.

Safety

• All new tools are strictly read-only — no transactions are constructed or signed
• No private key is required for any operation
• fund_testnet is guarded to reject mainnet usage
• No new dependencies added — uses existing @stellar/stellar-sdk and @langchain/core

[cubic-dev-ai]

5 issues found across 17 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tools/bridge.ts">

<violation number="1" location="tools/bridge.ts:172">
P2: Bridge responses no longer include the documented `targetChain` field, breaking the public return contract.</violation>
</file>

<file name="tools/contract.ts">

<violation number="1" location="tools/contract.ts:56">
P1: `swap` is stubbed out and no longer performs the contract swap, but still returns a success-like response.</violation>
</file>

<file name="tools/claim_balance_tool.ts">

<violation number="1" location="tools/claim_balance_tool.ts:8">
P2: Top-level env validation throws during import, which can crash startup even if this tool is never invoked.</violation>
</file>

<file name="lib/claimF.ts">

<violation number="1" location="lib/claimF.ts:21">
P2: Swallows `response.next()` failures and returns a partial claimable-balance list as if it were complete.</violation>

<violation number="2" location="lib/claimF.ts:42">
P2: Horizon endpoint and network passphrase can drift because they are derived from separate env vars without validation, causing transactions to be built for the wrong network.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

2 issues found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tools/stake.ts">

<violation number="1" location="tools/stake.ts:13">
P1: Default RPC URL is hardcoded to testnet and does not track STELLAR_NETWORK, so mainnet runs can be sent to the wrong Soroban endpoint when SOROBAN_RPC_URL is unset.</violation>
</file>

<file name="tools/contract.ts">

<violation number="1" location="tools/contract.ts:12">
P2: Hardcoded testnet RPC fallback can send mainnet runs to the wrong backend when STELLAR_NETWORK=mainnet and SOROBAN_RPC_URL is unset.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[efekrbas]

@daiwikmh