feat(lib): MAF runtime adapter behind the existing BaseRetailAgent surface

[Cataldir]

Problem statement

The agent runtime in lib/src/holiday_peak_lib/agents was built on a custom abstraction (BaseRetailAgent, AgentBuilder, ModelTarget / ModelInvoker). Microsoft Agent Framework (MAF, agent-framework>=1.0.1) and Microsoft Foundry now provide a stable, supported runtime that overlaps the same surface — agent loop, tool invocation, memory binding, model routing, telemetry — with first-party support and ongoing investment.

R1 (Microsoft Agent Framework backend cutover) starts with a new internal seam in lib/. This issue introduces lib/src/holiday_peak_lib/maf/runtime.py as the MAF-backed implementation that BaseRetailAgent will delegate to, leaving the public surface (BaseRetailAgent, AgentBuilder, FoundryAgentConfig) unchanged so service-side migrations in subsequent issues are mechanical.

Required change

• Add lib/src/holiday_peak_lib/maf/__init__.py and lib/src/holiday_peak_lib/maf/runtime.py implementing MafRuntime — an internal class that wraps the MAF agent loop and is delegated to from BaseRetailAgent defined in lib/src/holiday_peak_lib/agents/base_agent.py.
• Public API of BaseRetailAgent (in base_agent.py), AgentBuilder (in builder.py), and FoundryAgentConfig (in foundry.py) MUST remain unchanged. No app code should need to learn MAF idioms unless it explicitly opts in.
• Enforce MCP-only A2A (per ADR-030, landing in PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978): the runtime emits a mcp.hop counter and refuses non-MCP A2A egress.
• Emit OTEL spans per ADR-031 (landing in PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978): introduce a retail_span() helper colocated with the runtime that sets the canonical span attributes (agent.name, agent.context, model.target, mcp.hop, etc.).
• Bind three-tier memory per ADR-032 (landing in PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978): wire HotStore / WarmStore / ColdStore / MemoryFacade interfaces into the runtime so per-context memory bindings are pluggable.
• Pin agent-framework==1.0.1 (or the latest minor at R1 start) in pyproject.toml. Upgrades are a separate PR after R1 completes.

Affected components

• New module: lib/src/holiday_peak_lib/maf/runtime.py.
• Updated delegation in lib/src/holiday_peak_lib/agents/base_agent.py (public surface unchanged).
• New contract test file: lib/tests/test_maf_runtime.py.
• Dependency pin in pyproject.toml.

Acceptance criteria

• lib/src/holiday_peak_lib/maf/runtime.py shipped with MafRuntime and a retail_span() helper.
• BaseRetailAgent, AgentBuilder, FoundryAgentConfig public surfaces are byte-identical (signatures, return types, public attributes).
• MCP-only A2A enforced: any non-MCP A2A egress raises a typed error; mcp.hop counter increments per hop.
• OTEL spans emitted per ADR-031 attribute contract (advisory until ADR-031 merges via PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978; final attribute names will follow that ADR).
• Three-tier memory bound per ADR-032: MemoryFacade exposes Hot/Warm/Cold stores; bindings are injected by AgentBuilder.
• Contract tests in lib/tests/test_maf_runtime.py proving parity with the legacy surface for at least: handle() request flow, model routing (SLM→LLM upgrade per ADR-010), MCP tool registration, span emission, memory read/write.
• Test coverage ≥ 90 % for lib/src/holiday_peak_lib/maf/.
• python -m pylint lib/src apps/**/src clean (no new findings; truth-* baseline assumes PR chore(lint): clear pylint baseline in truth-* services #979 has merged).
• python -m pytest lib/tests green.
• lib/README.md updated with the new internal seam and a "no public API change" call-out.

Risks and dependencies

Risk	Mitigation
MAF 1.0.1 introduces a breaking change before R1 completes.	Pin agent-framework==1.0.1 (or the latest minor at R1 start). Upgrades are a separate PR after R1 completes.
The custom runtime had behaviors MAF doesn't expose.	Inventory of custom behaviors completed in this issue's design phase. Each is mapped to either MAF native, MAF extension point, or a lib/ adapter.
Reach-throughs into BaseRetailAgent internals exist in app code.	Pre-flight grep across apps/ for direct use of internal modules. Block per-context cutover until refactored.
OTEL / canary / memory ADRs not yet merged.	Acceptance criteria reference the ADR contracts loosely until PR #978 (ADRs 029–033) and PR #974 (ADR-028 continuous eval) merge; final span attribute names and eval keys are advisory and will be locked once those PRs land.

Soft prerequisite (advisory): PR #978 (ADRs 029–033) — span attribute, MCP-only A2A, AGC canary, three-tier memory contracts.
Soft prerequisite (advisory): PR #974 (ADR-028 continuous evaluation) — eval baselines used downstream are advisory until #974 merges.

Blocks: all 8 per-bounded-context cutover issues (this issue is the seam every context cutover depends on).

Evidence links

• lib/src/holiday_peak_lib/agents/base_agent.py
• lib/src/holiday_peak_lib/agents/builder.py
• lib/src/holiday_peak_lib/agents/foundry.py
• lib/src/holiday_peak_lib/agents/init.py
• lib/README.md
• pyproject.toml

ADR impact

• ADR-005 (agent framework) — refined: legacy BaseRetailAgent becomes a thin re-export over MAF.
• ADR-007 (memory tiers) — refined by ADR-032 (PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978): runtime binds the formal Hot/Warm/Cold contract.
• ADR-010 (model routing) — preserved: SLM→LLM upgrade behavior is parity with the legacy surface.
• ADR-024 (agent communication policy) — superseded by ADR-030 (PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978): MCP-only A2A.
• ADR-029, ADR-030, ADR-031, ADR-032 (PR docs(adr): ADR-029..033 - architecture contracts (canary, MCP A2A, OTEL, memory, UI on SWA) #978) — implemented by this seam.

Branch convention

feature/<issue-id>-maf-runtime-adapter (per ADR-018).

BPMN process

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#FFB3BA',
  'primaryTextColor':'#000',
  'primaryBorderColor':'#FF8B94',
  'lineColor':'#BAE1FF',
  'secondaryColor':'#BAE1FF',
  'tertiaryColor':'#FFFFFF'
}}}%%
flowchart LR
  A[Analyze Current Code] --> B[Design Change]
  B --> C[Implement on Issue Branch]
  C --> D[Open PR]
  D --> E[Validation and Fixes]
  E --> F[Merge to Main]
  F --> G[Monitor Workflows]
  G --> H[Close Issue and Cleanup]

Loading