Embed xcsh with the SDK

The coding-agent software development kit (SDK) embeds session creation, provider streaming, and tool registration. Use it when a host application needs in-memory control rather than a child-process transcript.

Which automation boundary should I choose?

Use --mode json, rpc, or acp for a process boundary. Use the SDK for direct TypeScript integration. Use xcsh worker for a headless extension bridge and xcsh manager for the detached control server that spawns and reaps workers.

How do I keep the integration testable?

Pin the package version, record protocol fixtures, close sessions and workers explicitly, and assert both final messages and tool events. Treat undocumented internal modules as unstable.

Create the smallest host around one session and one mock tool. Subscribe before sending the prompt so the test observes model deltas, the tool request, the tool result, and the final message in order. The host owns provider credentials, tool side effects, and shutdown; call the SDK close path even after an exception. A test passes only when no worker, timer, or transport remains after the session settles.