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

[chopmob-cloud]

Human-present crypto-solana scenario (AP2 + Solana Pay reference binding)

Adds a human-present AP2 sample where the buyer settles with on-chain USDC on Solana. It mirrors the existing x402 scenario but uses Solana Pay semantics, specifically the reference pubkey primitive, to bind the settling transaction deterministically to a signed PaymentMandate.

What it demonstrates

• A fresh single-use reference pubkey is embedded in the Solana Pay URL per checkout, so the wallet records it as a read-only account in the transfer.
• After the transfer is broadcast, getSignaturesForAddress(reference) locates the exact settling transaction without asking the buyer to paste a signature.
• Final verification checks the on-chain recipient, amount, and SPL mint against the PaymentMandate; all three must match. This is more robust than amount-uniqueness heuristics and more wallet-compatible than SPL memos.

Files

• code/samples/python/scenarios/a2a/human-present/crypto-solana/README.md
• code/samples/python/scenarios/a2a/human-present/crypto-solana/run.sh

Notes

• The scenario is facilitator-agnostic; any Solana-aware AP2 facilitator works. AlgoVoi is named only as one example. No facilitator API key is required to start the agents; GOOGLE_API_KEY (or GOOGLE_GENAI_USE_VERTEXAI=true) is the only required credential.
• SOLANA_RPC_URL defaults to the public Solana devnet endpoint for safe local testing; set a mainnet or paid RPC provider for real settlement.
• This PR also pins and hardens .github/workflows/linter.yaml (pinned action SHAs, scoped permissions, persist-credentials false, VALIDATE_BIOME_LINT false, and a code/web-client exclusion) to keep Lint Code Base and zizmor green. Rebased onto current main so the diff is only the scenario plus the linter hardening.

[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.

[chopmob-cloud]

Bumping for maintainer visibility -- Gemini review is satisfied (env sourcing and process tracking both approved in the April 29 pass).

Since then, the Solana Pay reference binding pattern this PR demonstrates has moved into production: the AlgoVoi gateway now settles on Solana in live agent payment flows using the same per-checkout reference pubkey approach. The MCP server (uvx algovoi-mcp / npx -y @algovoi/mcp-server) exposes Solana as one of 8 live chains for AI agents calling AP2-compatible payment tools.

Happy to rebase or split the PR if it would help.

-- AlgoVoi (chopmob-cloud)