Managed Agents: re-export ManagedBackendProtocol and unify retrieve_session schema

[MervinPraison]

Problem

Two discoverability / consistency gaps.

A1 — ManagedBackendProtocol hidden

The canonical managed-agents backend contract lives at src/praisonai-agents/praisonaiagents/agent/protocols.py:306-445, but the namespace a user would look in — praisonaiagents.managed.protocols — only exposes ComputeProviderProtocol (compute layer). Result:

from praisonaiagents.managed import ManagedBackendProtocol   # AttributeError
# vs
from praisonaiagents.agent.protocols import ManagedBackendProtocol  # works

This violates the principle that related protocols live together in the module namespace named after the feature.

A6 — retrieve_session() schema drift

AnthropicManagedAgent.retrieve_session (managed_agents.py:511-527) returns {id, status, usage: {input_tokens, output_tokens}} (sometimes no usage key). LocalManagedAgent.retrieve_session (managed_local.py:673-683) returns {id, status, usage: {input_tokens, output_tokens}} always. Both also have inconsistent handling of the title field.

Cross-provider code that reads info["title"] or info["usage"] without defaults breaks silently.

Acceptance criteria

• from praisonaiagents.managed import ManagedBackendProtocol works (re-export only, no move, no breaking change).
• praisonaiagents.managed.__all__ includes ManagedBackendProtocol.
• Shared SessionInfo dataclass (wrapper-side): {id: str, status: str, title: str, usage: {input_tokens: int, output_tokens: int}} — all fields always present (defaults: "", "unknown", "", {0,0}).
• Both retrieve_session() implementations return this dataclass (or its .to_dict() for back-compat); docstring documents the schema.
• Back-compat: old dict keys still present.
• Tests assert schema equality between Anthropic and Local return values.

Implementation plan

1. Edit src/praisonai-agents/praisonaiagents/managed/__init__.py to lazy-export ManagedBackendProtocol via __getattr__ (no eager import to keep module light).
2. Add src/praisonai/praisonai/integrations/_session_info.py with the SessionInfo dataclass + to_dict() for back-compat.
3. Update both retrieve_session() methods to build and return SessionInfo.
4. Unit tests comparing the two.

Files

Modify:

• src/praisonai-agents/praisonaiagents/managed/__init__.py
• src/praisonai/praisonai/integrations/managed_agents.py
• src/praisonai/praisonai/integrations/managed_local.py

Create:

• src/praisonai/praisonai/integrations/_session_info.py
• src/praisonai-agents/tests/managed/test_session_info_schema.py

Invariants

• Lazy imports preserved in core.
• Back-compat preserved (dict shape unchanged; dataclass is additive).

References

• Analysis: meta issue Meta: Managed Agents follow-ups — safety, observability, tests, CLI parity #1425.
• ManagedBackendProtocol definition: praisonaiagents/agent/protocols.py:306.

cc @claude.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job • claude/issue-1429-20260416-2118 • Create PR ➔

---

Issue #1429 Complete ✅

Successfully implemented managed agents re-export and unified retrieve_session schema.

Todo List:

• Setup git identity and read AGENTS.md guidelines
• Examine current codebase structure and protocols
• Re-export ManagedBackendProtocol from managed/init.py
• Create SessionInfo dataclass in _session_info.py
• Update AnthropicManagedAgent.retrieve_session implementation
• Update LocalManagedAgent.retrieve_session implementation
• Add unit tests for schema equality
• Test changes and ensure back-compatibility
• Commit and create PR

Implementation Summary:

✅ A1 — ManagedBackendProtocol re-export

• Added lazy __getattr__ to praisonaiagents/managed/__init__.py
• from praisonaiagents.managed import ManagedBackendProtocol now works
• Added to __all__ list for proper discoverability

✅ A6 — Unified retrieve_session schema

• Created SessionInfo dataclass in _session_info.py with fields: id, status, title, usage
• Updated AnthropicManagedAgent.retrieve_session() to return unified schema
• Updated LocalManagedAgent.retrieve_session() to return unified schema
• All fields always present with sensible defaults
• Full backward compatibility maintained

✅ Tests & Validation

• Added comprehensive test suite in tests/managed/test_session_info_schema.py
• Verified schema equality between Anthropic and Local backends
• Confirmed backward compatibility with existing dict access patterns
• All tests passing

---

[MervinPraison]

@claude please implement this focused PR. Related merged PRs: #1432, #1433, #1434. Please rebase on latest main before opening. Scope is praisonaiagents/managed/__init__.py re-export + _session_info.py dataclass + both backends' retrieve_session methods.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job • claude/issue-1429-20260417-0542 • Create PR ➔

---

Issue #1429 Complete ✅

Successfully implemented managed agents re-export and unified retrieve_session schema.

Todo List:

• Setup git identity and read AGENTS.md guidelines
• Rebase on latest main
• Examine current codebase structure and protocols
• Re-export ManagedBackendProtocol from managed/init.py
• Create SessionInfo dataclass in _session_info.py
• Update AnthropicManagedAgent.retrieve_session implementation
• Update LocalManagedAgent.retrieve_session implementation
• Add unit tests for schema equality
• Test changes and ensure back-compatibility
• Commit and create PR

Implementation Summary:

✅ A1 — ManagedBackendProtocol re-export

• Added lazy __getattr__ to praisonaiagents/managed/__init__.py
• from praisonaiagents.managed import ManagedBackendProtocol now works
• Added to __all__ list for proper discoverability

✅ A6 — Unified retrieve_session schema

• Created SessionInfo dataclass in _session_info.py with fields: id, status, title, usage
• Updated AnthropicManagedAgent.retrieve_session() to return unified schema
• Updated LocalManagedAgent.retrieve_session() to return unified schema
• All fields always present with sensible defaults
• Full backward compatibility maintained

✅ Tests & Validation

• Added comprehensive test suite in tests/managed/test_session_info_schema.py
• Verified schema equality between Anthropic and Local backends
• Confirmed backward compatibility with existing dict access patterns
• All tests passing

---

**** • Branch: claude/issue-1429-20260417-0542