Repository navigation
bug: on_connect arg is AgentSideConnection at runtime while methods and params are different than Client #49
Description
Summary
Type Client and AgentSideConnection are not the same, while on_connect params is a Client, it is a AgentSideConnection at runtime (
Line 59 in 4cc2dfd
There is a cast forced here
https://github.com/agentclientprotocol/python-sdk/blob/main/src/acp/agent/connection.py#L64
When using Client, there are method such as create_terminal that does not return the same values nor property
I really like the move to snake case, but I think it added a lot of breaking changes, especially to load the Agent. Shouldn't this release have been a major ?
Reproduction steps
class ExampleAgent(Agent)
#...
@override
def on_connect(self, conn: Client) -> None:
self.client = conn
# ^ this is AgentSideConnection at runtime terminal_handle = await client.create_terminal(...)
print(terminal_handle.terminal_id)
# ^ this break because terminal_handle is not `CreateTerminalResponse` with `terminal_id` but `TerminalHandle` with `id`Also, having Client and AgentSideConnection being different type with no inheritence + AgenceSideConnection being now final make the test harder to write, especially when you need to stub AgentSideConnection
Expected result
Client and AgentSideConnection should have similar property so that the types expected at runtime are the same. I'd expect on_connect to receive an AgentSideConnection instead of Client which is a protocol
Actual result
class ExampleAgent(Agent)
#...
@override
def on_connect(self, conn: Client) -> None:
self.client = conn
# ^ this is AgentSideConnection at runtime terminal_handle = await client.create_terminal(...)
print(terminal_handle.terminal_id)
# ^ this break because terminal_handle is not `CreateTerminalResponse` with `terminal_id` but `TerminalHandle` with `id`Versions / environment
sdk 0.7.0, Python 3.12, macOS 15.7.3
Quick fix for now is to force cast Client into AgentSideConnection
Activity
[-]bug: `on_connect` arg is `AgentSideConnection` at runtime but methods and params are different[/-][+]bug: `on_connect` arg is `AgentSideConnection` at runtime while methods and params are different than `Client`[/+]benbrandt commentedon Dec 19, 2025
Small note: it is fairly common pre-1.0 to have the second slot of semver equal "major", so I think the versioning is correct here
PsiACE commentedon Dec 19, 2025
I’ve shared a temporary fix in #50. I’ll try to include it in a near-term release.
Nemtecl commentedon Dec 21, 2025
Nice thank you 🙏 Looking forward to this future release 🚀
Nemtecl commentedon Dec 27, 2025
Hi @PsiACE 👋
I saw that the PR was merged, awesome ! No rush at all, but do you have a rough estimate for when the next release with the fix might drop? Just curious for planning purposes! 😊
PsiACE commentedon Dec 28, 2025
I'll double-check with @stdrc . He's been working on bumping the schema recently and might have a better solution.
If we don't need #52 for now, I will release a 0.7.1 today for this fix.
PsiACE commentedon Dec 28, 2025
https://github.com/agentclientprotocol/python-sdk/releases/tag/0.7.1
A version containing #50 has been released, and the protocol schema has been upgraded to 0.10.2.
stdrc commentedon Dec 29, 2025
I feel that we should let the
client.create_terminalreturn terminal ID, fully respect the protocol. Then provide another level of thin wrapper to implement theTerminalHandleabstraction. Does that look good to you?Nemtecl commentedon Dec 29, 2025
I do not have any strong opinion on this ! 😄
I'm totally fine with
create_terminalstrictly returning theIDlike specified in the protocolI think ideally we should have
AgentSideConnectionextendingClientso that we avoid casting when usingon_connect, wdyt ?frostming commentedon Jan 3, 2026
I hope that
AgentSideConnectionandClientSideConnectionare hidden from the user at runtime. And users shouldn't call properties or methods beyond theClientorAgentprotocol. What do you want by casting the type? This sounds like an abstraction leakage to me.Nemtecl commentedon Jan 7, 2026
Sorry if my comment was ambiguous
What I meant by casting is that we enforce the casting from AgentSideConnection to Client here : https://github.com/agentclientprotocol/python-sdk/blob/main/src/acp/agent/connection.py#L65
And because AgentSideConnection does not inherit from the Client Protocol, we are not 100% sure methods signatures are the same when using it, meaning that, at runtime, when you check the type of the parameters of
on_connect, it's an AgentSideConnection (expected because it's what is sent but it also can lead to issues when same methods name has different signature, like what was done for create_terminal in 0.7.0)I would think that a way of fixing that and keeping the AgentSideConnection hidden for the users would be to avoid the casting line 65 and instead ensure signatures are the same by having AgentSideConnection extending Client, what do you think of that ?
frostming commentedon Jan 7, 2026
make sense, so the above fix needs to be improved
frostming commentedon Jan 8, 2026
I don't see how the thin wrapper should look like, because
TerminalHandleholds an internal objectconnfrom a private classAgentSideConnection, ifAgentSideConnection.create_terminalstrictly returns aCreateTerminalResponse, then there is no way for callers to construct theTerminalHandlethemselves.BTW, I am aware that
TerminalHandleoffers some convenient helpers for managing the terminal; however, using them goes beyond the protocol, and abstraction leakage seems inevitable if we continue to rely on this class.Is there any real use case using
TerminalHandleor should we remove it for now given there are equivalent in Client protocol for those helper methods? @stdrc @PsiACEPsiACE commentedon Jan 8, 2026
I had some discussions with stdrc a few weeks ago, and I believe removal for now is a reliable option.