feat: Redesign the APIs to be more intuitive, and make them backward-compatible

[frostming]

Summary

Note

This PR is stacked on #36 and should not be merged before that one.

As title

Related issues

Previously, the agent-side and client-side APIs are rather symmetric, making it confusing when choosing which connection should be used. For me it takes me a while to understand AgentSideConnection is created by agent but exposes the same API set as the client. Moreover, the fact it taking a callable as first parameter is not very Pythonic to me, because in Python you have to pass it via a lambda.

So I added two new APIs to replace the two connection classes, while the latter should be considered an implementation detail.

• run_agent(agent), called by agent developers, to start listening to client requests. It will block until cancelled or error, similar to server.listen(), which users are more familiar with.
• connect_to_agent(client), called by client, to create a connection(ClientSideConnection) to the agent and it can be used like an agent

The first argument takes an agent or client instance respectively, rather than a callable. If the agent or client depends on the connection for interoperability, it should define a method def on_connect, which will be called by the connection's __init__ method if possible. See the change in example/echo_agent.py for how it looks like.

In the meantime, ClientSideConnection and AgentSideConnection are deprecated as public APIs. Users importing it from the top level module will see a warning. A migration guide is good to add, this is on the To-do list. A migration guide is added.

It's 100% backward-compatible, I wrote a new test file test_compatibility.py to ensure it.

Testing

Docs & screenshots

Checklist

• Conventional Commit title (e.g. feat:, fix:).
• Tests cover the change or are not required (explain above).
• Docs/examples updated when behaviour is user-facing.
• Schema regenerations (make gen-all) are called out if applicable.

[frostming]

See how it looks like in a real-world app: MoonshotAI/kimi-cli@main...frostming:kimi-cli:feat/acp-0.7

[PsiACE]

fucking LGTM! Merge!