feat(instrument): Port Agentforce framework adapter (M2)

[mmercuri]

Summary

Ports the Salesforce Agentforce framework adapter from ateam (stratix.sdk.python.adapters.agentforce, ~2,954 LOC across 11 files — the largest of the M2 framework batch) onto the layerlens.instrument base layer landed in M1.A (#93). Self-contained: this PR can be reviewed and merged independent of the other M2 fan-out PRs.

Source path: A:/github/layerlens/ateam/stratix/sdk/python/adapters/agentforce/ (adapter, auth, client, events, importer, llm_eval, mapper, models, normalizer, trust_layer, __init__).

Template: langchain framework adapter — same package layout (per-concern modules, ADAPTER_CLASS lazy-loading marker, __all__ reexport, requires_pydantic compat hint).

Salesforce Agentforce specifics

This adapter is import-mode rather than runtime monkey-patching: Agentforce is a remote multi-tenant REST service, not a Python library, so there is no in-process SDK to instrument. The adapter:

• Authenticates with OAuth 2.0 JWT Bearer (PyJWT + RS256). SalesforceCredentials accepts the private key as raw PEM, an env:NAME reference, or a filesystem path.
• Backfills traces by running SOQL against five Data Cloud DMOs (AIAgentSession, AIAgentSessionParticipant, AIAgentInteraction, AIAgentInteractionStep, AIAgentInteractionMessage).
• Exposes companion modules for Agent API REST real-time capture (client.py + mapper.py), Platform Events subscription via gRPC Pub/Sub with CometD long-polling fallback (events.py), Einstein Trust Layer policy round-trip (trust_layer.py), and an LLM evaluator (llm_eval.py).
• Includes hardening from the original port: SOQL injection guards (every parent ID validated against the 15/18-char Salesforce ID regex; date / timestamp params validated against ISO 8601 regexes), token re-authentication on expiry, and Sforce-Limit-Info rate-limit warnings at 80% consumption.
• to_stratix_policy(...) is retained as a DeprecationWarning alias for to_layerlens_policy(...) so existing stratix.* callers still work for one migration window.

What's in the PR

Path	Purpose
src/layerlens/instrument/adapters/frameworks/agentforce/ (11 files)	Full port of the source package
src/layerlens/instrument/adapters/frameworks/__init__.py	Lazy package marker (no eager SDK imports)
tests/instrument/adapters/frameworks/test_agentforce.py (36 tests)	SDK-shape mocks; no real Salesforce or network call
samples/instrument/agentforce/main.py + README.md	Runnable end-to-end sample (4 mocked flows + opt JWT)
docs/adapters/frameworks-agentforce.md	Integration guide incl. OAuth Connected App setup
pyproject.toml	New agentforce extra (requests + PyJWT[crypto])

M2 fan-out

This PR is part of the M2 framework adapter fan-out — one self-contained PR per heavy framework (Agentforce is the largest by LOC). It depends on M1.A (#93 — instrument base foundation) but is independent of the other M2 PRs.

Acceptance criteria status

• mypy --strict src/layerlens/instrument/adapters/frameworks/agentforce → Success: no issues found in 11 source files
• ruff check src/.../agentforce tests/.../test_agentforce.py → All checks passed
• pytest tests/instrument/adapters/frameworks/test_agentforce.py → 36 passed
• pytest tests/instrument/test_default_install.py → 3 passed (the new agentforce extra does not perturb the default install set)
• python samples/instrument/agentforce/main.py → exit 0, prints all four flow summaries

Test plan

• CI: mypy --strict clean on the new package
• CI: ruff check clean on the new package + test
• CI: pytest tests/instrument/adapters/frameworks/test_agentforce.py green (36 tests)
• CI: default-install guard (tests/instrument/test_default_install.py) green — confirms the agentforce extra is opt-in
• Reviewer: read docs/adapters/frameworks-agentforce.md OAuth Connected App section against current Salesforce Setup screens
• Reviewer: spot-check auth.py JWT signing payload + retry logic for parity with the source port
• Reviewer: confirm to_stratix_policy deprecation alias matches the rename pattern adopted elsewhere in the M2 batch