Canonicalize Resources Before Lifecycle Side Effects
Pass the same server object to a manager twice and a seemingly harmless list duplication can become two connections, two cleanup calls and two entries in failure accounting. Suppressing the second connect locally would fix only one symptom. Retry and cleanup could still rediscover the duplicate under different rules.
An OpenAI Agents Python change merged on 2026-08-23 places the invariant earlier. MCPServerManager canonicalizes its incoming server collection before establishing the population it owns. Connect and reverse-order cleanup operate on that population, while retry and cleanup subsets reuse the same uniqueness helper. A regression using the same object twice observes one managed entry, one connect and one cleanup.
The transferable proposition is: a lifecycle-owning component should decide what it owns before it performs side effects. The identity relation behind that decision must be explicit, and the resulting guarantee remains local. Canonicalization plus a manager lock is not endpoint uniqueness or distributed exactly-once execution.
Deduplicate at the ownership boundary
Per-operation deduplication is attractive because it can be added beside the failure. A duplicate connect appears, so connect filters its input. Later, cleanup gains its own filter. Retry introduces another subset. Each path can then preserve a different order, choose a different key or forget normalization entirely.
Constructor-time canonicalization changes the abstraction. The manager first defines _all_servers, then derives its active, failed and cleanup populations from one owned set. The selected implementation preserves the first occurrence and reuses normalization when internal subsets are formed. The resource count is stable before the first side effect.
This is an ownership-admission invariant: a resource becomes eligible for lifecycle actions only after the manager has placed it in the canonical population. It is easier to audit because connect, retry and cleanup can be compared against the same reference set. It is also easier to test under partial failure because every phase starts from a known population rather than reconstructing identity independently.
If a system can prove duplicates are impossible, or if every external operation is safely idempotent, central normalization may add little value. That is a legitimate simpler contract. The assumption should be explicit, because an iterable assembled from plugins, dependency injection or configuration often makes duplicate ownership possible in ways the manager cannot see locally.
Identity is part of the lifecycle contract
The helper uses Python set membership. In the tested case, the same server object is supplied twice, and the base class does not define custom equality. But the algorithm is more accurately equality-based than an unconditional is-identity rule. A subclass with custom __eq__ and __hash__ could cause distinct instances to collapse.
That may be correct or dangerous depending on the ownership model. Two wrappers can point to the same endpoint but intentionally carry different credentials or session state. Conversely, two objects can represent one logical server and should perhaps share ownership. Endpoint URL, object identity, value equality and a logical resource key answer different questions.
The contract should therefore name the relation and its consequences: which representative is retained, whether order matters, how credentials and sessions affect uniqueness, and whether a changed key creates a new lifecycle identity. Leaving the rule implicit in container behavior makes correctness depend on class implementation details that may change outside the manager.
A lock and a unique set solve different failures
MCPServerManager also serializes lifecycle mutations with an asynchronous lock. That prevents participating operations inside one manager from overlapping in time. It does not reduce the number of resources the manager believes it owns. Canonicalization controls population cardinality; the lock controls temporal concurrency.
Both are useful. A unique population without serialization can still suffer connect and cleanup races. A lock around a duplicated population can execute the same side effect twice in perfect sequence. Tests should cover these guarantees independently: duplicate inputs, concurrent lifecycle calls, partial connect failure, retry subsets, reverse-order cleanup and cleanup errors.
Reusing one uniqueness helper across internal subsets matters for the same reason. If the failed-server list or cleanup set can reintroduce duplicates, the constructor invariant no longer governs the entire lifecycle. The guarantee must cover every path named in the contract, not only the happy-path connect loop.
Exactly-once begins beyond the process boundary
The demonstrated evidence is process-local. Another manager, process or host can still own a wrapper for the same endpoint. A connect can partially succeed before returning an error. Cleanup can fail, be cancelled or be retried. No external receipt in the selected change establishes that the endpoint observed each effect exactly once.
A stronger claim needs evidence at the external boundary: idempotency keys understood by the service, durable operation receipts, leases or ownership records shared across managers, and reconciliation after ambiguous outcomes. Local call counts are valuable regression evidence, but they cannot prove what happened outside the process.
The final design question is therefore not “Did the manager call connect() once?” It is “Which identity did the external system observe, and what durable evidence lets another owner distinguish completed, failed and ambiguous effects?” Canonical ownership makes that question easier to ask. It does not answer it by itself.
Primary evidence: OpenAI Agents Python merged commit 042d84a1. The implementation and regression support the bounded in-process behavior described here; they are not independent proof of endpoint uniqueness or distributed exactly-once execution.