feat(agent-memory): add access_strategy and tenant params for multitenancy

[cassiofariasmachado]

Disclaimer: Do not include SAP-internal or customer-specific information in this PR (e.g. internal system URLs, customer names, tenant IDs, or confidential configurations). This is a public repository.

Description

Adds multitenancy support to the agent_memory module by introducing an AccessStrategy enum and tenant parameter on every public client method. All reads and writes can now be scoped to either the provider tenant or a subscriber tenant, with the subscriber token URL derived automatically from the service binding's identityzone.

This closes AFSDK-4011.

Supported strategies (explicit only, no silent fallback):

• SUBSCRIBER_ONLY (default) — fetches a subscriber-scoped OAuth2 token using the provided tenant subdomain. Raises AgentMemoryValidationError if tenant is omitted.
• PROVIDER_ONLY — uses the provider token; no tenant required.

Breaking change: existing calls that omit tenant will raise AgentMemoryValidationError because the default strategy is SUBSCRIBER_ONLY. Migration: pass tenant="<subdomain>" or access_strategy=AccessStrategy.PROVIDER_ONLY.

Related Issue

Closes #

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Code refactoring
• Dependency update

How to Test

1. Run unit tests: pytest tests/agent_memory/unit/ — all 232 tests should pass
2. Run integration tests with provider credentials only: pytest tests/agent_memory/integration/ — 14 provider scenarios pass, 12 subscriber scenarios skip
3. Run integration tests with subscriber tenant configured: CLOUD_SDK_CFG_HANA_AGENT_MEMORY_DEFAULT_SUBSCRIBER_TENANT=<subdomain> pytest tests/agent_memory/integration/ — all 26 scenarios pass

Checklist

• I have read the Contributing Guidelines
• I have verified that my changes solve the issue
• I have added/updated automated tests to cover my changes
• All tests pass locally
• I have verified that my code follows the Code Guidelines
• I have updated documentation (if applicable)
• I have added type hints for all public APIs
• My code does not contain sensitive information (credentials, tokens, etc.)
• I have followed Conventional Commits for commit messages

Breaking Changes

What breaks: Any call to an AgentMemoryClient method without tenant now raises AgentMemoryValidationError (default strategy is SUBSCRIBER_ONLY).

Migration path:

# Before
client.list_memories(agent_id="my-agent", invoker_id="user-1")

# After — subscriber tenant
client.list_memories(agent_id="my-agent", invoker_id="user-1",
                     access_strategy=AccessStrategy.SUBSCRIBER_ONLY, tenant="my-subdomain")

# After — provider (no tenant needed)
client.list_memories(agent_id="my-agent", invoker_id="user-1",
                     access_strategy=AccessStrategy.PROVIDER_ONLY)

Additional Notes

• Token caching is per tenant subdomain — provider and subscriber tokens are cached independently in HttpTransport._oauth_cache.
• The identityzone field is now parsed from the UAA JSON binding and stored in AgentMemoryConfig. It is used to derive the subscriber token URL via string replacement, following the same pattern as the destination module.
• BDD integration tests use a single Given I use the configured subscriber tenant step to flip the strategy, so all scenario step implementations are shared between provider and subscriber test suites (no duplication).
• The _FIRST fallback strategies (SUBSCRIBER_FIRST, PROVIDER_FIRST) are explicitly deferred pending safety evaluation of silent cross-tenant fallback behaviour.