feat(samples): add human-present crypto-solana scenario (AP2 + Solana Pay reference binding)

[chopmob-cloud]

Adds a new human-present A2A scenario: `code/samples/python/scenarios/a2a/human-present/crypto-solana/`.

What this adds

A parallel to the existing `cards`, `x402`, and open `crypto-algo` (PR #218) scenarios — settling on Solana using on-chain USDC (SPL Token) with Solana Pay `reference` pubkey binding for deterministic tx↔mandate correlation.

Why `reference` binding matters here

Solana has no native transaction memo field (unlike Algorand / Hedera), and the SPL Memo Program is inconsistently supported across wallets. The canonical Solana Pay primitive for binding a settling transaction to a specific order is a `reference` pubkey — a fresh ed25519 public key included as a read-only, non-signer account on the transfer instruction:

```
solana:?amount=&spl-token=<USDC_MINT>&reference=<burner_pubkey>&label=...&message=<mandate_id>
```

After settlement, the Merchant Payment Processor Agent resolves the transaction deterministically via `getSignaturesForAddress()`. This is:

• Cryptographically unique per checkout (256-bit entropy)
• Wallet-universal — every Solana Pay–compliant wallet attaches the reference automatically
• Non-interactive from the buyer's side — no need to paste a tx signature back

Scope

Minimal and additive — two files under `code/samples/python/scenarios/a2a/human-present/crypto-solana/`:

• `README.md` — full flow documentation including env var reference
• `run.sh` — launcher (starts Merchant, CP, MPP agents, then Shopping Agent via ADK web)

Uses the shared role agents already in `code/samples/python/src/roles/`. No changes to existing files.

Prerequisites

```
GOOGLE_API_KEY or GOOGLE_GENAI_USE_VERTEXAI=true
ALGOVOI_API_KEY # sign up at https://cloud.algovoi.co.uk
SOLANA_RPC_URL # defaults to public mainnet endpoint if not set
```

Happy to sign the Google CLA as per PR #218.

[gemini-code-assist]

Code Review

This pull request introduces a new sample scenario for human-present transactions using on-chain Solana USDC, including a detailed README on the Solana Pay reference binding mechanism and a shell script to orchestrate the necessary agents. Feedback was provided regarding the order of environment variable sourcing in the startup script to prevent unintended overrides from local configuration files and to improve the robustness of the cleanup process by initializing process tracking earlier.

[gemini-code-assist]

The PAYMENT_METHOD environment variable is set at line 12, but then .env is sourced at line 25. If the user has PAYMENT_METHOD defined in their .env file, it will override the scenario-specific value (CRYPTO_SOLANA), potentially causing the script to execute with the wrong payment logic. It is safer to source the .env file first and then set scenario-specific overrides. Additionally, initializing the pids array early ensures that the cleanup trap (line 80) is always safe even if the script fails during early setup (e.g., line 20).

Suggested change

	export PAYMENT_METHOD=CRYPTO_SOLANA
	AGENTS_DIR="samples/python/src/roles"
	LOG_DIR=".logs"
	if [ ! -d "$AGENTS_DIR" ]; then
	echo "Error: Directory '$AGENTS_DIR' not found."
	echo "Please run this script from the root of the repository."
	exit 1
	fi
	if [ -f .env ]; then
	set -a
	source .env
	set +a
	fi
	if [ -f .env ]; then
	set -a
	source .env
	set +a
	fi
	export PAYMENT_METHOD=CRYPTO_SOLANA
	AGENTS_DIR="samples/python/src/roles"
	LOG_DIR=".logs"
	pids=()
	if [ ! -d "$AGENTS_DIR" ]; then
	echo "Error: Directory '$AGENTS_DIR' not found."
	echo "Please run this script from the root of the repository."
	exit 1
	fi

[chopmob-cloud]

This is already addressed in the current commit. PAYMENT_METHOD=CRYPTO_SOLANA is exported on line 13, before .env is processed. The while IFS= loop then uses [[ -v "$key" ]] to skip any variable that is already present in the environment — so a PAYMENT_METHOD entry in .env cannot override the scenario value. The result is identical to your suggestion (scenario value always wins) but the guard applies to every variable, not just PAYMENT_METHOD.

[chopmob-cloud]

Thanks for the review @gemini-code-assist. Both points addressed in the latest commit:

• Env var sourcing order: replaced set -a; source .env; set +a with a while IFS= loop that skips any variable already present in the calling environment. This means shell-exported variables always take precedence over values in .env, rather than being silently overwritten.

• Process tracking initialisation: moved pids=() to before the cleanup() function definition and trap cleanup EXIT, so the cleanup handler is safe to call at any point in the script's lifecycle — including early exits during uv sync.

[gemini-code-assist]

Thanks for the update, @chopmob-cloud. The changes to the environment variable sourcing and the process tracking initialization look solid and address the concerns raised. The use of a while loop for .env sourcing is a much safer approach, and moving the pids initialization ensures the cleanup function is robust against early exits. This looks good to go.