fix(sdk): raise asyncio StreamReader buffer in Python AsyncHostTransport

[michaelreavant]

Summary

superdoc_get_content on larger documents fails in the Python async SDK with a misleading HOST_DISCONNECTED error. Root cause is a missing limit= on the subprocess spawn — the stdout StreamReader inherits asyncio's 64 KiB default buffer, which any non-trivial response trips. This PR raises the buffer ceiling and exposes it as a configurable option.

Problem

The Python async transport spawned the host CLI without passing a limit= to asyncio.create_subprocess_exec, so its stdout StreamReader inherited asyncio's default 64 KiB buffer. Every host response is written as a single newline-delimited JSON line, so any cli.invoke whose serialized result exceeds 64 KiB (e.g. superdoc_get_content on larger documents) caused readline() to raise ValueError: Separator is not found, and chunk exceed the limit inside _reader_loop. The exception was caught by the generic reader-loop handler and pending requests were rejected with the misleading HOST_DISCONNECTED error — even though the host process was still alive and healthy.

Fix

Pass limit= to create_subprocess_exec and expose it as a new stdout_buffer_limit_bytes constructor option on AsyncHostTransport, threaded through SuperDocAsyncRuntime and AsyncSuperDocClient. The default of 64 MiB safely covers the host's own 32 MiB DEFAULT_MAX_STDIN_BYTES input cap with room for ~2x JSON expansion.

Scope

SyncHostTransport is unaffected — it uses raw blocking subprocess.Popen which has no asyncio buffer limit. No changes to the Node SDK or the host server.

Tests

Adds a TestAsyncLargeResponse regression suite that:

1. Round-trips a 200 KB response through the default-configured transport.
2. Pins that an explicitly tightened stdout_buffer_limit_bytes still reproduces the original failure mode, guaranteeing the option is wired through to create_subprocess_exec.

Bug reproduction was verified by stashing the fix and running the new test against the unmodified transport.py — it raised the exact SuperDocError: Host process disconnected. seen in production. With the fix in place, the full Python SDK test suite passes (90 tests, including 26 transport tests).

Test plan

• pytest packages/sdk/langs/python/tests/ — 90 passed
• Verified regression test reproduces the original HOST_DISCONNECTED failure when the fix is reverted
• pnpm run generate:all clean (no codegen drift in this branch)

[caio-pizzol]

@michaelreavant — fix is right, flagging a few things before merge.

the main one: when the buffer limit is hit, the error handler at transport.py:619-631 marks the transport as disconnected but doesn't kill the host process. a later dispose() sees the state as already disconnected and returns early, so the host keeps running. your PR raises the ceiling (64 MiB vs 64 KiB) but doesn't close this gap — any caller who sets stdout_buffer_limit_bytes below their real response size will leave host processes running in the background.

fix: in the except Exception branch, kill the process and clear self._process before flipping state. the cleanest way is to schedule a _cleanup task from that branch.

while you're there: the error code on that path is still HOST_DISCONNECTED, which points people at the wrong problem since the host didn't actually die. catching ValueError / asyncio.LimitOverrunError separately and surfacing HOST_PROTOCOL_ERROR with a "raise stdout_buffer_limit_bytes" hint would be much more actionable.

smaller notes inline.

[caio-pizzol]

this exposes the bug down at transport.py:619-631 — see the summary. the fix belongs in that branch, not here.

[caio-pizzol]

64 * 1024 * 1024 also lives in runtime.py:82 and client.py:343. hoist a module-level constant so tuning is one place:

Suggested change

	stdout_buffer_limit_bytes: int = 64 * 1024 * 1024,
	stdout_buffer_limit_bytes: int = _DEFAULT_STDOUT_BUFFER_LIMIT_BYTES,

(and define _DEFAULT_STDOUT_BUFFER_LIMIT_BYTES = 64 * 1024 * 1024 at module scope, then reference it from the three signatures)

[caio-pizzol]

short note on when to raise this — today the reason only lives in a comment in transport.py.

Suggested change

	stdout_buffer_limit_bytes: int = 64 * 1024 * 1024,
	stdout_buffer_limit_bytes: int = 64 * 1024 * 1024, # raise if responses exceed 64 MiB

[caio-pizzol]

64kb refers to the old default — after this PR it's 64 MiB, so the name reads backwards.

Suggested change

	async def test_response_above_default_64kb_buffer(self):
	async def test_response_above_asyncio_default_streamreader_limit(self):

[caio-pizzol]

no await transport.dispose() on this path, so the host is left running after the test. wrap in try/finally like the sibling tests:

Suggested change

	try:
	transport = AsyncHostTransport(
	cli,
	startup_timeout_ms=5_000,
	stdout_buffer_limit_bytes=64 * 1024,
	)
	await transport.connect()
	with pytest.raises(SuperDocError) as exc_info:
	await transport.invoke(_TEST_OP, {'query': 'big'})
	assert exc_info.value.code == HOST_DISCONNECTED
	finally:
	_cleanup_wrapper(cli)
	try:
	transport = AsyncHostTransport(
	cli,
	startup_timeout_ms=5_000,
	stdout_buffer_limit_bytes=64 * 1024,
	)
	await transport.connect()
	with pytest.raises(SuperDocError) as exc_info:
	await transport.invoke(_TEST_OP, {'query': 'big'})
	assert exc_info.value.code == HOST_DISCONNECTED
	await transport.dispose()
	finally:
	_cleanup_wrapper(cli)

[caio-pizzol]

both tests build AsyncHostTransport directly, so if someone drops the arg in client.py or runtime.py the public API breaks silently while these still pass. worth one small test that builds AsyncSuperDocClient(env={'SUPERDOC_CLI_BIN': cli}, stdout_buffer_limit_bytes=64*1024) and checks the value reaches the transport.

[michaelreavant]

@caio-pizzol Thank you for the review! All issues were addressed.