Roadmap: core Managed Agents API alignment

[yanpgwang]

Summary

Track verifiable compatibility with the core single-agent Claude Managed Agents API before expanding to the broader product surface in #60.

Route presence alone does not count as compatibility. A capability is complete only when it is usable through the official SDK, honors every accepted field, and has coverage at the appropriate wire, service, and durability layers.

Status

Mango exposes all 21 core SDK-visible HTTP operations. The scoped core conformance gate is complete; broader product surfaces remain tracked in #60.

HTTP contract

• Agent and Environment list pagination and filtering (feat: paginate agent and environment lists #59)
• Agent Version pagination and SDK auto-paging (feat: paginate agent version history #61)
• Core validation, defaults, null handling, and error contract
  • Reject unsupported fields in stored MCP server definitions (fix: reject unsupported MCP server fields #62)
  • Reject unsupported fields in executable tool definitions (fix: reject unsupported Agent tool fields #63)
  • Reject malformed optional values in executable tool definitions (fix: reject malformed Agent tool values #64)
  • Enforce custom tool required fields and documented bounds (fix: enforce custom tool admission contract #65)
  • Enforce Agent tool collection and MCP config name bounds (fix: enforce Agent tool collection bounds #66)
  • Validate nested Session Event content shapes (fix(httpapi): validate nested event content #79)
  • Order and paginate events by processed time (fix(events): paginate by processed time #84)
  • Reject null for non-nullable Agent and Session fields (fix(httpapi): reject null non-nullable fields #87)
• Environment update with real networking and package enforcement
  • Enforce default unrestricted cloud networking in sandbox provisioning (fix: enforce default cloud sandbox networking #70)
  • Add the safe Environment update route and SDK coverage (feat: implement Environment update #71)
  • Accept explicit unrestricted networking and empty package sets (feat: accept explicit Environment defaults #72)
  • Install configured packages before sandbox binding (feat(environment): enforce configured package setup #89)
  • Enforce limited networking through capable sandbox providers (feat(environment): enforce limited networking #91)
• Usable OpenAPI schemas and official SDK black-box coverage for every core endpoint
  • Align Environment lifecycle wire defaults and SDK coverage (fix: align Environment lifecycle wire defaults #68)
  • Persist Environment description, metadata, and self-hosted scope (feat: persist Environment resource fields #69)
  • Exercise Session archive through the official SDK (test: cover Session archive through SDK #73)
  • Define resource lifecycle OpenAPI schemas (docs: define lifecycle OpenAPI schemas #74)
  • Define Session Event and SSE OpenAPI schemas (docs(api): define Session Event OpenAPI contract #75)

Runtime and event contract

• Complete the documented core event union and correlation invariants
  • Publish the remaining core single-agent event variants (feat(events): complete core single-agent variants #81)
  • Preserve core span, MCP, retry, and preview correlation (feat: emit documented agent.mcp_tool_use and agent.mcp_tool_result events #56, feat(events): publish outcome evaluation heartbeats #78, feat(runtime): publish model retry lifecycle #80, fix(stream): fence previews by model request #82)
• Normalize evaluated permission fields for executed built-in and MCP calls
  • Report evaluated permissions on executed tool calls (fix(events): report evaluated tool permissions #76)
• Verify retry, terminal-state, heartbeat, and finish-preview behavior
  • Normalize terminal Session error events (fix(events): normalize terminal Session errors #77)
  • Publish durable outcome-evaluation heartbeats (feat(events): publish outcome evaluation heartbeats #78)
  • Publish the observable model retry lifecycle (feat(runtime): publish model retry lifecycle #80)
  • Fence delayed previews by model request (fix(stream): fence previews by model request #82)
  • Publish start-only thinking previews (feat(stream): publish thinking start previews #83)
• Verify SSE ordering, reconnection, backpressure, and restart behavior
  • Exercise process replacement and subscriber backpressure (test(stream): verify recovery and backpressure #85)
• Verify context projection, tool-result legality, interruption races, and ambiguous side effects
  • Isolate context projections and preserve tool-result legality (feat: align core managed agent session semantics #48, fix(context): isolate request projections #88)
  • Linearize interrupts and fence ambiguous side effects (Platform spine: Temporal/PostgreSQL orchestration and durable tool journal #12, feat: durable cross-process session interrupts #29, feat: reconcile sandbox lifecycle crash windows #40)

Conformance gate

• Add a compact differential matrix based on official documentation and SDK types (docs: add core API conformance matrix #67)
• Add service and replay coverage for durable state transitions
  • Cover every current Workflow version-gate boundary (test(temporal): cover workflow version gates #86)
• Run opt-in live conformance for safe, observable behavior
  • Exercise live text and sandbox tool turns (test: add service and live model conformance #43, test: add live model tool conformance #49)
• Document every remaining compatibility limitation (docs: publish core compatibility statement #92)
• Publish a versioned core compatibility statement (docs: publish core compatibility statement #92)

In scope

• Agents: create, list, get, update, versions, archive
• Environments: create, list, get, update, archive, delete
• Sessions: create, list, get, update, archive, delete
• Session Events: send, list, stream
• Single-agent execution: model turns, built-in tools, custom tools, MCP tools, confirmations, interrupts, outcomes, and durable restart recovery

Out of scope

The following official surfaces are tracked by #60 and do not block this milestone:

• Files and Session Resources
• Skills
• Memory Stores and Vaults
• Deployments and Deployment Runs
• Multi-agent Session Threads
• The self-hosted Environment Work API
• Parity with undocumented wording or Anthropic-internal infrastructure

Architecture constraints

• PostgreSQL is the source of truth for accepted state and the public event ledger.
• Temporal owns recoverable in-flight orchestration.
• NATS may provide ephemeral wakeups and previews, but correctness must not depend on message retention.
• Configuration must not be accepted unless the runtime can honor it; unsupported behavior must fail explicitly.

References

• Agents
• Environments
• Sessions
• Session Events

[yanpgwang]

Delivered in #59: Agent and Environment list pagination and filtering, with wire, official Go SDK, and PostgreSQL coverage. Environment update and runtime configuration enforcement were intentionally kept out of scope.

[yanpgwang]

Delivered in #61: Agent Version pagination, endpoint-scoped cursor validation, official Go SDK auto-paging coverage, and PostgreSQL coverage.

Follow-up database work remains for the Agent latest-page query shape and Environment list indexes.