Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Make response stream lifetimes explicit (#1060)
Ali Khokhar5ffa47fbc39d
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 0397ec22..906c3161 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -236,10 +236,12 @@ configures logging, constructs the runtime owners and the configured voicethe consumer-owned ports in [application/ports.py](src/free_claude_code/application/ports.py); Admin operations retaintheir inbound-adapter port in [api/ports.py](src/free_claude_code/api/ports.py).-[api/app.py](src/free_claude_code/api/app.py) registers routers, HTTP correlation middleware, and exception handlers around-an explicit `ApiServices` value. It does not read global settings or construct-runtime resources. `app.state.services` is the only runtime state published to-FastAPI.+[api/app.py](src/free_claude_code/api/app.py) registers routers and exception+handlers around an explicit `ApiServices` value, then wraps the application in a+pure ASGI correlation boundary. The boundary surrounds the complete wire send;+it does not proxy streaming responses through `BaseHTTPMiddleware`. The API does+not read global settings or construct runtime resources.+`app.state.services` is the only runtime state published to FastAPI.[runtime/application.py](src/free_claude_code/runtime/application.py) owns process startup and shutdown, optional messaging,the selected transcriber, the managed CLI session manager, Admin pending state,@@ -261,15 +263,17 @@ the concise startup-failure contract.[runtime/provider_manager.py](src/free_claude_code/runtime/provider_manager.py) is the only owner that constructs, publishes,retires, and closes provider generations. Each request acquires a generationlease before routing. Non-streaming responses release it after aggregation;-streaming responses release it from the response iterator's `finally` path on-completion, failure, cancellation, or disconnect. A provider-only Admin Apply-prepares a candidate and commits configuration before publication. New requests-then use the candidate while old streams finish on the retired generation; its-last lease closes it exactly once. Final shutdown rejects new acquisition and-replacement, waits every lease, and awaits the same manager-owned cleanup task-even if the initiating request or lease release is cancelled. Failed generation-or unpublished-candidate cleanup remains owned and retryable; the manager does-not become terminal or clear its model catalog until every owned runtime closes.+streaming responses bind it to FCC's response owner, which first closes the+entire body chain and then releases the lease on completion, failure,+cancellation, disconnect, or a response-start send failure. A provider-only+Admin Apply prepares a candidate and commits configuration before publication.+New requests then use the candidate while old streams finish on the retired+generation; its last lease closes it exactly once. Final shutdown rejects new+acquisition and replacement, waits every lease, and awaits the same+manager-owned cleanup task even if the initiating request or lease release is+cancelled. Failed generation or unpublished-candidate cleanup remains owned and+retryable; the manager does not become terminal or clear its model catalog until+every owned runtime closes.The manager also owns one application-lifetime provider model catalog and itssingle best-effort discovery task. The catalog survives provider replacement.@@ -352,11 +356,16 @@ proxy auth is disabled. Otherwise the token may be supplied through `x-api-key`,`Authorization: Bearer ...`, or `anthropic-auth-token`. Comparisons useconstant-time matching.-HTTP request correlation is owned at ingress. Middleware creates one opaque FCC-request ID before routing, places it in log context and request state, and adds-`request-id` to every response. OpenAI-compatible Responses and the shared model-catalog also expose the same value as `x-request-id`. Provider execution and-trace events receive that existing ID; they do not create a second identifier.+HTTP request correlation is owned at ingress. A pure ASGI boundary creates one+opaque FCC request ID before routing, places it in log context and request state,+and adds `request-id` while forwarding the actual `http.response.start` message.+OpenAI-compatible Responses and the shared model catalog also expose the same+value as `x-request-id`. Provider execution and trace events receive that+existing ID; they do not create a second identifier. Keeping the context around+the complete inner ASGI call preserves correlation during streaming and leaves+response lifetime finalization under the concrete response owner. Starlette's+outer server-error boundary bypasses user middleware for its catch-all 500, so+that one handler explicitly attaches the same ingress-owned headers.[api/handlers/](src/free_claude_code/api/handlers/) owns the public API product flows.`MessagesHandler` validates non-empty messages, resolves models, applies@@ -372,15 +381,29 @@ it does not depend on FastAPI, provider implementations, or the full settingsobject.[api/response_streams.py](src/free_claude_code/api/response_streams.py) owns public streaming egresscommit timing. It waits for the first protocol chunk before returning a-successful `StreamingResponse`. A provider-execution failure before that commit-boundary remains a real typed non-2xx JSON response. Once FCC has finalized the-failure, the response includes `x-should-retry: false` so FCC retains ownership-of upstream retry/recovery without causing a second client retry loop. After the-first chunk has escaped, HTTP status is committed; Messages emits an Anthropic-`event: error` and closes without a synthetic `message_stop`; Responses emits-`response.failed` with the original response ID. Non-streaming Messages-aggregate internally and return non-2xx JSON for any terminal stream error,-discarding incomplete content rather than presenting a partial success.+successful FCC-owned `StreamingResponse`. Its explicit replay iterator owns the+prefetched stream even before replay begins. The response itself owns one+idempotent finalization task: close the body transitively, then release the+provider-generation lease. This finalizer surrounds the real ASGI send and runs+to completion even when sending headers or the first body frame fails. A provider+execution failure before that commit boundary remains a real typed non-2xx JSON+response. Once FCC has finalized the failure, the response includes+`x-should-retry: false` so FCC retains ownership of upstream retry/recovery+without causing a second client retry loop. After the first chunk has escaped,+HTTP status is committed; Messages emits an Anthropic `event: error` and closes+without a synthetic `message_stop`; Responses emits `response.failed` with the+original response ID. Non-streaming Messages aggregate internally and return+non-2xx JSON for any terminal stream error, discarding incomplete content rather+than presenting a partial success.++The public response chain follows a transitive close-ownership rule. A response+owns its replay iterator; replay owns the active protocol adapter; each protocol+adapter owns its direct input; tracing owns the executor body; the executor body+owns the provider iterator; and the provider runner owns its upstream stream.+Each of these response-chain owners closes its direct input on normal completion,+failure, cancellation, and early consumer close. Failures from those explicit+cleanup calls are trace metadata and cannot replace an established wire outcome;+a generation lease is released only after the body chain has finished closing.Ingress authentication, request validation, model routing, and deterministicpreflight failures remain ordinary HTTP errors and do not receive the terminaldiff --git a/pyproject.toml b/pyproject.tomlindex 2e328e2d..20d142c3 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "3.5.5"+version = "3.5.6"description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"readme = "README.md"requires-python = ">=3.14.0"diff --git a/src/free_claude_code/api/app.py b/src/free_claude_code/api/app.pyindex b3349413..330bdd1f 100644--- a/src/free_claude_code/api/app.py+++ b/src/free_claude_code/api/app.py@@ -25,10 +25,9 @@ from .admin_routes import router as admin_routerfrom .ports import ApiServicesfrom .request_errors import ordinary_application_error_responsefrom .request_ids import (+ RequestCorrelationMiddleware,attach_request_id_headers,get_request_id,- new_request_id,- set_request_id,)from .routes import routerfrom .validation_log import summarize_request_validation_body@@ -38,26 +37,7 @@ def create_app(services: ApiServices) -> FastAPI:"""Create the HTTP adapter around explicitly supplied runtime services."""app = FastAPI(title="Claude Code Proxy", version=package_version())app.state.services = services-- @app.middleware("http")- async def trace_http_correlation(request: Request, call_next):- """Attach HTTP identifiers and optional Claude session id to logs."""- request_id = new_request_id()- set_request_id(request, request_id)- claude_sid = extract_claude_session_id_from_headers(request.headers)- with logger.contextualize(- http_method=request.method,- http_path=request.url.path,- claude_session_id=claude_sid,- request_id=request_id,- ):- response = await call_next(request)- attach_request_id_headers(- response,- request_id=request_id,- path=request.url.path,- )- return response+ app.add_middleware(RequestCorrelationMiddleware)app.include_router(admin_router)app.include_router(router)diff --git a/src/free_claude_code/api/request_ids.py b/src/free_claude_code/api/request_ids.pyindex ba67a182..6ffe5ae1 100644--- a/src/free_claude_code/api/request_ids.py+++ b/src/free_claude_code/api/request_ids.py@@ -3,6 +3,11 @@import uuidfrom fastapi import Request, Response+from loguru import logger+from starlette.datastructures import Headers, MutableHeaders+from starlette.types import ASGIApp, Message, Receive, Scope, Send++from free_claude_code.core.trace import extract_claude_session_id_from_headersREQUEST_ID_HEADER = "request-id"OPENAI_REQUEST_ID_HEADER = "x-request-id"@@ -10,6 +15,51 @@ _REQUEST_ID_STATE_ATTRIBUTE = "fcc_request_id"_OPENAI_REQUEST_ID_PATHS = frozenset({"/v1/responses", "/v1/models"})+class RequestCorrelationMiddleware:+ """Own one request id and logging context for the full ASGI response."""++ def __init__(self, app: ASGIApp) -> None:+ self._app = app++ async def __call__(+ self,+ scope: Scope,+ receive: Receive,+ send: Send,+ ) -> None:+ if scope["type"] != "http":+ await self._app(scope, receive, send)+ return++ request_id = new_request_id()+ state = scope.setdefault("state", {})+ state[_REQUEST_ID_STATE_ATTRIBUTE] = request_id+ method = scope.get("method", "")+ path = scope.get("path", "")+ request_headers = Headers(scope=scope)+ claude_sid = extract_claude_session_id_from_headers(request_headers)++ async def send_with_correlation(message: Message) -> None:+ if message["type"] == "http.response.start":+ message = dict(message)+ raw_headers = list(message.get("headers", ()))+ _set_request_id_headers(+ MutableHeaders(raw=raw_headers),+ request_id=request_id,+ path=path,+ )+ message["headers"] = raw_headers+ await send(message)++ with logger.contextualize(+ http_method=method,+ http_path=path,+ claude_session_id=claude_sid,+ request_id=request_id,+ ):+ await self._app(scope, receive, send_with_correlation)++def new_request_id() -> str:"""Return a new opaque FCC request identifier."""return f"req_{uuid.uuid4().hex}"@@ -33,7 +83,16 @@ def get_request_id(request: Request) -> str:def attach_request_id_headers(response: Response, *, request_id: str, path: str) -> None:- """Expose FCC correlation using the public protocol header names."""- response.headers[REQUEST_ID_HEADER] = request_id+ """Attach correlation when an outer server-error boundary bypasses middleware."""+ _set_request_id_headers(response.headers, request_id=request_id, path=path)+++def _set_request_id_headers(+ headers: MutableHeaders,+ *,+ request_id: str,+ path: str,+) -> None:+ headers[REQUEST_ID_HEADER] = request_idif path in _OPENAI_REQUEST_ID_PATHS:- response.headers[OPENAI_REQUEST_ID_HEADER] = request_id+ headers[OPENAI_REQUEST_ID_HEADER] = request_iddiff --git a/src/free_claude_code/api/response_streams.py b/src/free_claude_code/api/response_streams.pyindex 94d26a27..a66833e5 100644--- a/src/free_claude_code/api/response_streams.py+++ b/src/free_claude_code/api/response_streams.py@@ -2,16 +2,17 @@import asynciofrom collections.abc import (- AsyncGenerator,- AsyncIterable,AsyncIterator,Awaitable,Callable,Mapping,)-from typing import Any, Literal, Protocol, runtime_checkable+from typing import Any, Literalfrom fastapi.responses import JSONResponse, Response, StreamingResponse+from starlette.background import BackgroundTask+from starlette.responses import ContentStream+from starlette.types import Receive, Scope, Sendfrom free_claude_code.core.anthropic import anthropic_error_type_for_failurefrom free_claude_code.core.anthropic.streaming import (@@ -19,9 +20,10 @@ from free_claude_code.core.anthropic.streaming import (anthropic_terminal_error_frame,anthropic_terminal_failure_frame,)+from free_claude_code.core.async_iterators import try_close_async_iteratorfrom free_claude_code.core.diagnostics import safe_exception_messagefrom free_claude_code.core.failures import find_execution_failure-from free_claude_code.core.trace import trace_event+from free_claude_code.core.trace import close_stream_input, trace_eventTERMINAL_EXECUTION_ERROR_HEADERS = {"x-should-retry": "false"}@@ -32,44 +34,143 @@ ReleaseResponseResource = Callable[[], Awaitable[None]]WireApi = Literal["messages", "responses"]-@runtime_checkable-class _AsyncCloseable(Protocol):- async def aclose(self) -> None: ...--class EmptyStreamError(RuntimeError):"""Raised when a public stream ends before emitting any protocol chunk."""+class ManagedStreamingResponse(StreamingResponse):+ """Own body closure and one response-scoped runtime release callback."""++ def __init__(+ self,+ content: ContentStream,+ status_code: int = 200,+ headers: Mapping[str, str] | None = None,+ media_type: str | None = None,+ background: BackgroundTask | None = None,+ ) -> None:+ super().__init__(+ content,+ status_code=status_code,+ headers=headers,+ media_type=media_type,+ background=background,+ )+ self._release: ReleaseResponseResource | None = None+ self._cleanup_task: asyncio.Task[None] | None = None++ def bind_release(self, release: ReleaseResponseResource) -> None:+ """Bind the resource retained for this response before ASGI execution."""+ if self._release is not None:+ raise RuntimeError("A response resource release is already bound.")+ if self._cleanup_task is not None:+ raise RuntimeError("Cannot bind a resource after response cleanup started.")+ self._release = release++ async def aclose(self) -> None:+ """Close the body and release its runtime resource exactly once."""+ await self._close(preserved_error=None)++ async def _close(self, *, preserved_error: BaseException | None) -> None:+ task = self._cleanup_task+ if task is None:+ task = asyncio.create_task(+ self._cleanup(preserved_error=preserved_error),+ name="fcc-api-response-cleanup",+ )+ self._cleanup_task = task+ await _wait_for_cleanup(task)++ async def __call__(+ self,+ scope: Scope,+ receive: Receive,+ send: Send,+ ) -> None:+ preserved_error: BaseException | None = None+ try:+ await super().__call__(scope, receive, send)+ except BaseException as exc:+ preserved_error = exc+ raise+ finally:+ await self._close(preserved_error=preserved_error)++ async def _cleanup(self, *, preserved_error: BaseException | None) -> None:+ try:+ await close_stream_input(+ self.body_iterator,+ owner="ManagedStreamingResponse",+ source="api",+ preserved_error=preserved_error,+ )+ except Exception as exc:+ _trace_response_cleanup_failure("close_body", exc)++ release = self._release+ if release is None:+ return+ try:+ await release()+ except Exception as exc:+ _trace_response_cleanup_failure("release_resource", exc)+++async def _wait_for_cleanup(task: asyncio.Task[None]) -> None:+ """Wait through repeated caller cancellation, then restore cancellation."""+ cancellation: asyncio.CancelledError | None = None+ while not task.done():+ try:+ await asyncio.shield(task)+ except asyncio.CancelledError as exc:+ cancellation = exc++ # Ordinary defensive failures are trace-only; cancellation remains control flow.+ try:+ task.result()+ except asyncio.CancelledError:+ if cancellation is not None:+ raise cancellation from None+ raise+ except Exception as exc:+ _trace_response_cleanup_failure("cleanup_task", exc)++ if cancellation is not None:+ raise cancellation+++def _trace_response_cleanup_failure(operation: str, exc: BaseException) -> None:+ trace_event(+ stage="egress",+ event="free_claude_code.api.response.cleanup_failed",+ source="api",+ operation=operation,+ exc_type=type(exc).__name__,+ )++async def bind_response_lifetime(response: object,release: ReleaseResponseResource,) -> object:"""Retain a runtime resource until a response body is fully consumed."""- if isinstance(response, StreamingResponse):- response.body_iterator = _release_after_stream(- response.body_iterator,- release,- )+ if isinstance(response, ManagedStreamingResponse):+ response.bind_release(release)return response- await release()- return response---async def _release_after_stream(- body: AsyncIterable[Any],- release: ReleaseResponseResource,-) -> AsyncGenerator[Any]:- iterator = body.__aiter__()- try:- async for chunk in iterator:- yield chunk- finally:+ if isinstance(response, StreamingResponse):+ error = TypeError("Streaming API responses must use ManagedStreamingResponse.")try:- if isinstance(iterator, _AsyncCloseable):- await iterator.aclose()+ await close_stream_input(+ response.body_iterator,+ owner="bind_response_lifetime",+ source="api",+ preserved_error=error,+ )finally:await release()+ raise error+ await release()+ return responsedef terminal_execution_error_response(@@ -122,20 +223,24 @@ async def _first_chunk_streaming_response(try:first_chunk = await anext(body)except StopAsyncIteration:- return pre_start_error_response(- EmptyStreamError("Stream ended before emitting a response.")- )- except GeneratorExit:+ error = EmptyStreamError("Stream ended before emitting a response.")+ await _close_pre_start_body(body, preserved_error=error)+ return pre_start_error_response(error)+ except GeneratorExit as exc:+ await _close_pre_start_body(body, preserved_error=exc)raise- except asyncio.CancelledError:+ except asyncio.CancelledError as exc:+ await _close_pre_start_body(body, preserved_error=exc)raiseexcept BaseExceptionGroup as exc:+ await _close_pre_start_body(body, preserved_error=exc)return pre_start_error_response(exc)except Exception as exc:+ await _close_pre_start_body(body, preserved_error=exc)return pre_start_error_response(exc)- return StreamingResponse(- _replay_first_chunk_then_stream(+ return ManagedStreamingResponse(+ _PrefetchedStream(first_chunk,body,terminal_frame=terminal_frame,@@ -146,34 +251,78 @@ async def _first_chunk_streaming_response()-async def _replay_first_chunk_then_stream(- first_chunk: str,+async def _close_pre_start_body(body: AsyncIterator[str],*,- terminal_frame: TerminalFrameEmitter | None,- terminal_failure_observer: TerminalFailureObserver | None,-) -> AsyncGenerator[str]:- yield first_chunk- try:- async for chunk in body:- yield chunk- except GeneratorExit:- raise- except asyncio.CancelledError:- raise- except BaseExceptionGroup as exc:- if terminal_frame is None:+ preserved_error: BaseException,+) -> None:+ task = asyncio.create_task(+ close_stream_input(+ body,+ owner="first_chunk_streaming_response",+ source="api",+ preserved_error=preserved_error,+ ),+ name="fcc-api-pre-start-stream-cleanup",+ )+ await _wait_for_cleanup(task)+++class _PrefetchedStream(AsyncIterator[str]):+ """Replay one prefetched frame while retaining ownership of the tail."""++ def __init__(+ self,+ first_chunk: str,+ body: AsyncIterator[str],+ *,+ terminal_frame: TerminalFrameEmitter | None,+ terminal_failure_observer: TerminalFailureObserver | None,+ ) -> None:+ self._first_chunk: str | None = first_chunk+ self._body = body+ self._terminal_frame = terminal_frame+ self._terminal_failure_observer = terminal_failure_observer+ self._done = False+ self._closed = False++ def __aiter__(self) -> _PrefetchedStream:+ return self++ async def __anext__(self) -> str:+ if self._closed or self._done:+ raise StopAsyncIteration+ if self._first_chunk is not None:+ first_chunk = self._first_chunk+ self._first_chunk = None+ return first_chunk+ try:+ return await anext(self._body)+ except StopAsyncIteration:+ self._done = Trueraise- terminal_error = find_execution_failure(exc) or exc- if terminal_failure_observer is not None:- terminal_failure_observer(terminal_error)- yield terminal_frame(terminal_error)- except Exception as exc:+ except BaseExceptionGroup as exc:+ return self._terminal_chunk(find_execution_failure(exc) or exc)+ except Exception as exc:+ return self._terminal_chunk(exc)++ async def aclose(self) -> None:+ if self._closed:+ return+ self._closed = True+ self._done = True+ close_error = await try_close_async_iterator(self._body)+ if close_error is not None:+ raise close_error++ def _terminal_chunk(self, exc: BaseException) -> str:+ terminal_frame = self._terminal_frameif terminal_frame is None:- raise- if terminal_failure_observer is not None:- terminal_failure_observer(exc)- yield terminal_frame(exc)+ raise exc+ self._done = True+ if self._terminal_failure_observer is not None:+ self._terminal_failure_observer(exc)+ return terminal_frame(exc)async def anthropic_sse_streaming_response(diff --git a/src/free_claude_code/application/execution.py b/src/free_claude_code/application/execution.pyindex 3a15640d..0e1c3f52 100644--- a/src/free_claude_code/application/execution.py+++ b/src/free_claude_code/application/execution.py@@ -1,5 +1,6 @@"""Provider execution shared by inbound API adapters."""+import sysfrom collections.abc import AsyncIterator, Callablefrom typing import Literal@@ -12,7 +13,11 @@ from free_claude_code.core.anthropic import (anthropic_request_snapshot,get_token_count,)-from free_claude_code.core.trace import trace_event, traced_async_stream+from free_claude_code.core.trace import (+ close_stream_input,+ trace_event,+ traced_async_stream,+)from .ports import ProviderResolverfrom .routing import RoutedMessagesRequest@@ -96,13 +101,24 @@ class ProviderExecutor:)async def provider_body() -> AsyncIterator[str]:- async for chunk in provider.stream_response(- routed.request,- input_tokens=input_tokens,- request_id=request_id,- thinking_enabled=routed.resolved.thinking_enabled,- ):- yield chunk+ provider_stream: AsyncIterator[str] | None = None+ try:+ provider_stream = provider.stream_response(+ routed.request,+ input_tokens=input_tokens,+ request_id=request_id,+ thinking_enabled=routed.resolved.thinking_enabled,+ )+ async for chunk in provider_stream:+ yield chunk+ finally:+ if provider_stream is not None:+ await close_stream_input(+ provider_stream,+ owner="provider_executor",+ source="api",+ preserved_error=sys.exception(),+ )stream_trace: dict[str, object] = {"request_id": request_id,diff --git a/src/free_claude_code/core/async_iterators.py b/src/free_claude_code/core/async_iterators.pynew file mode 100644index 00000000..589ac26f--- /dev/null+++ b/src/free_claude_code/core/async_iterators.py@@ -0,0 +1,26 @@+"""Minimal lifecycle helpers for composed asynchronous iterators."""++from typing import Protocol, runtime_checkable+++@runtime_checkable+class AsyncCloseable(Protocol):+ """An object whose asynchronous iteration resources can be released."""++ async def aclose(self) -> None: ...+++async def try_close_async_iterator(value: object) -> Exception | None:+ """Close ``value`` when supported, returning ordinary cleanup failures.++ Cancellation remains control flow and propagates to the caller. Returning+ ordinary exceptions lets an owner observe cleanup failure without replacing+ the stream outcome that was already established.+ """+ if not isinstance(value, AsyncCloseable):+ return None+ try:+ await value.aclose()+ except Exception as exc:+ return exc+ return Nonediff --git a/src/free_claude_code/core/openai_responses/anthropic_sse.py b/src/free_claude_code/core/openai_responses/anthropic_sse.pyindex 5ad95098..10f47943 100644--- a/src/free_claude_code/core/openai_responses/anthropic_sse.py+++ b/src/free_claude_code/core/openai_responses/anthropic_sse.py@@ -1,10 +1,13 @@"""Anthropic SSE parsing used by the Responses stream adapter."""import json+import sysfrom collections.abc import AsyncIterable, AsyncIteratorfrom dataclasses import dataclassfrom typing import Any+from free_claude_code.core.trace import close_stream_input+@dataclass(slots=True)class AnthropicSseEvent:@@ -16,22 +19,31 @@ async def iter_sse_events(chunks: AsyncIterable[Any],) -> AsyncIterator[AnthropicSseEvent]:buffer = ""- async for chunk in chunks:- if isinstance(chunk, bytes):- buffer += chunk.decode("utf-8", errors="replace")- else:- buffer += str(chunk)-- while "\n\n" in buffer:- raw, buffer = buffer.split("\n\n", 1)- event = parse_sse_event(raw)+ iterator = aiter(chunks)+ try:+ async for chunk in iterator:+ if isinstance(chunk, bytes):+ buffer += chunk.decode("utf-8", errors="replace")+ else:+ buffer += str(chunk)++ while "\n\n" in buffer:+ raw, buffer = buffer.split("\n\n", 1)+ event = parse_sse_event(raw)+ if event is not None:+ yield event++ if buffer.strip():+ event = parse_sse_event(buffer)if event is not None:yield event-- if buffer.strip():- event = parse_sse_event(buffer)- if event is not None:- yield event+ finally:+ await close_stream_input(+ iterator,+ owner="openai_responses.anthropic_sse",+ source="core",+ preserved_error=sys.exception(),+ )def parse_sse_event(raw: str) -> AnthropicSseEvent | None:diff --git a/src/free_claude_code/core/openai_responses/stream.py b/src/free_claude_code/core/openai_responses/stream.pyindex 510764e8..833c31e1 100644--- a/src/free_claude_code/core/openai_responses/stream.py+++ b/src/free_claude_code/core/openai_responses/stream.py@@ -1,11 +1,13 @@"""Translate Anthropic SSE streams into OpenAI Responses SSE streams."""import asyncio+import sysfrom collections.abc import AsyncIterable, AsyncIterator, Callablefrom typing import Anyfrom free_claude_code.core.diagnostics import safe_exception_messagefrom free_claude_code.core.failures import ExecutionFailure, find_execution_failure+from free_claude_code.core.trace import close_stream_inputfrom .anthropic_sse import iter_sse_eventsfrom .models import OpenAIResponsesRequest@@ -23,8 +25,9 @@ async def iter_responses_sse_from_anthropic("""Yield Responses SSE events translated from an Anthropic SSE stream."""assembler = ResponsesStreamAssembler(request)emitted_any_chunk = False+ events = iter_sse_events(chunks)try:- async for event in iter_sse_events(chunks):+ async for event in events:for chunk in assembler.process_anthropic_event(event):yield chunkemitted_any_chunk = True@@ -63,6 +66,13 @@ async def iter_responses_sse_from_anthropic(_observe_post_start_terminal_failure(on_post_start_terminal_failure, exc)for chunk in assembler.fail_response(_unexpected_error_data(exc)):yield chunk+ finally:+ await close_stream_input(+ events,+ owner="openai_responses.stream",+ source="core",+ preserved_error=sys.exception(),+ )def _observe_post_start_terminal_failure(diff --git a/src/free_claude_code/core/trace.py b/src/free_claude_code/core/trace.pyindex 9eb822a3..121928d1 100644--- a/src/free_claude_code/core/trace.py+++ b/src/free_claude_code/core/trace.py@@ -6,11 +6,14 @@ sanitized credential keys (e.g. ``api_key``, ``authorization``)."""import asyncio+import sysfrom collections.abc import AsyncGenerator, AsyncIterator, Mappingfrom typing import Anyfrom loguru import logger+from free_claude_code.core.async_iterators import try_close_async_iterator+TRACE_PAYLOAD_BINDING = "trace_payload"_SECRET_VALUE_KEYS = frozenset(@@ -58,6 +61,29 @@ def trace_event(*, stage: str, event: str, source: str, **fields: Any) -> None:logger.bind(trace_payload=payload).info("TRACE {}", event)+async def close_stream_input(+ iterator: object,+ *,+ owner: str,+ source: str,+ preserved_error: BaseException | None,+) -> None:+ """Close one transform input and observe cleanup failure without raising it."""+ close_error = await try_close_async_iterator(iterator)+ if close_error is None:+ return+ trace_event(+ stage="lifecycle",+ event="stream.input.close_failed",+ source=source,+ owner=owner,+ close_exc_type=type(close_error).__name__,+ preserved_exc_type=(+ type(preserved_error).__name__ if preserved_error is not None else None+ ),+ )++def extract_claude_session_id_from_headers(headers: Mapping[str, str]) -> str | None:"""Best-effort session id forwarded by Claude Code / SDK via HTTP."""lowered = {str(k).lower(): v for k, v in headers.items() if isinstance(v, str)}@@ -143,6 +169,13 @@ async def traced_async_stream(**common,)raise+ finally:+ await close_stream_input(+ agen,+ owner="traced_async_stream",+ source=source,+ preserved_error=sys.exception(),+ )if not interrupted:trace_event(diff --git a/src/free_claude_code/providers/base.py b/src/free_claude_code/providers/base.pyindex 6e39827a..66692f3a 100644--- a/src/free_claude_code/providers/base.py+++ b/src/free_claude_code/providers/base.py@@ -124,7 +124,7 @@ class BaseProvider(ABC):return model_infos_from_ids(await self.list_model_ids())@abstractmethod- async def stream_response(+ def stream_response(self,request: MessagesRequest,input_tokens: int = 0,@@ -133,7 +133,3 @@ class BaseProvider(ABC):thinking_enabled: bool | None = None,) -> AsyncIterator[str]:"""Stream response in Anthropic SSE format."""- # Typing: abstract async generators need a yield for AsyncIterator[str]- # inference; this branch is never executed.- if False:- yield ""diff --git a/src/free_claude_code/providers/transports/anthropic_messages/transport.py b/src/free_claude_code/providers/transports/anthropic_messages/transport.pyindex ae9b50a2..ce8c81a8 100644--- a/src/free_claude_code/providers/transports/anthropic_messages/transport.py+++ b/src/free_claude_code/providers/transports/anthropic_messages/transport.py@@ -24,6 +24,7 @@ from free_claude_code.core.anthropic.streaming import (tool_schemas_by_name,)from free_claude_code.core.trace import (+ close_stream_input,provider_native_messages_body_snapshot,trace_event,)@@ -200,7 +201,7 @@ class AnthropicMessagesTransport(BaseProvider):)return send_response- async def stream_response(+ def stream_response(self,request: MessagesRequest,input_tokens: int = 0,@@ -216,22 +217,30 @@ class AnthropicMessagesTransport(BaseProvider):request_id=request_id,thinking_enabled=thinking_enabled,)- async for event in runner.run():- yield event+ return runner.run()async def _iter_sse_events(response: httpx.Response) -> AsyncIterator[str]:"""Group line-delimited upstream data into complete SSE events."""event_lines: list[str] = []- async for line in response.aiter_lines():- if line:- event_lines.append(line)- continue+ lines = response.aiter_lines()+ try:+ async for line in lines:+ if line:+ event_lines.append(line)+ continue+ if event_lines:+ yield "\n".join(event_lines) + "\n\n"+ event_lines.clear()if event_lines:yield "\n".join(event_lines) + "\n\n"- event_lines.clear()- if event_lines:- yield "\n".join(event_lines) + "\n\n"+ finally:+ await close_stream_input(+ lines,+ owner="anthropic_messages.sse_lines",+ source="provider",+ preserved_error=sys.exception(),+ )class _AnthropicMessagesStreamRunner:@@ -285,6 +294,7 @@ class _AnthropicMessagesStreamRunner:async with self._transport._rate_limiter.concurrency_slot():while True:stream_opened = False+ chunks: AsyncIterator[str] | None = Nonetry:response = await self._transport._rate_limiter.execute_with_retry(self._transport._validated_stream_send,@@ -296,11 +306,12 @@ class _AnthropicMessagesStreamRunner:chunk_count = 0chunk_bytes = 0- async for chunk in self._iter_stream_chunks(+ chunks = self._iter_stream_chunks(response,state=state,thinking_enabled=thinking_enabled,- ):+ )+ async for chunk in chunks:chunk_count += 1chunk_bytes += len(chunk.encode("utf-8", errors="replace"))for parsed in parse_sse_text(chunk):@@ -446,6 +457,13 @@ class _AnthropicMessagesStreamRunner:recovery.discard()raise failure from errorfinally:+ if chunks is not None:+ await close_stream_input(+ chunks,+ owner="anthropic_messages.runner",+ source="provider",+ preserved_error=sys.exception(),+ )if response is not None and not response.is_closed:await close_provider_stream(response,@@ -462,14 +480,23 @@ class _AnthropicMessagesStreamRunner:thinking_enabled: bool,) -> AsyncIterator[str]:"""Yield normalized grouped SSE events from the provider stream."""- async for event in _iter_sse_events(response):- output_event = transform_native_sse_block_event(- event,- state,- thinking_enabled=thinking_enabled,+ events = _iter_sse_events(response)+ try:+ async for event in events:+ output_event = transform_native_sse_block_event(+ event,+ state,+ thinking_enabled=thinking_enabled,+ )+ if output_event is not None:+ yield output_event+ finally:+ await close_stream_input(+ events,+ owner="anthropic_messages.block_policy",+ source="provider",+ preserved_error=sys.exception(),)- if output_event is not None:- yield output_eventdef _new_ledger(self) -> AnthropicStreamLedger:return AnthropicStreamLedger(diff --git a/src/free_claude_code/providers/transports/openai_chat/transport.py b/src/free_claude_code/providers/transports/openai_chat/transport.pyindex 9339b010..7323bec4 100644--- a/src/free_claude_code/providers/transports/openai_chat/transport.py+++ b/src/free_claude_code/providers/transports/openai_chat/transport.py@@ -235,7 +235,7 @@ class OpenAIChatTransport(BaseProvider):)return clamped- async def stream_response(+ def stream_response(self,request: MessagesRequest,input_tokens: int = 0,@@ -251,8 +251,7 @@ class OpenAIChatTransport(BaseProvider):request_id=request_id,thinking_enabled=thinking_enabled,)- async for event in runner.run():- yield event+ return runner.run()class _OpenAIChatStreamRunner:diff --git a/tests/api/test_request_ids.py b/tests/api/test_request_ids.pynew file mode 100644index 00000000..29219b75--- /dev/null+++ b/tests/api/test_request_ids.py@@ -0,0 +1,140 @@+"""Tests for the pure-ASGI ingress correlation owner."""++import asyncio+from collections.abc import Iterator+from contextlib import contextmanager+from typing import cast+from unittest.mock import patch++import pytest+from fastapi import Request+from starlette.datastructures import Headers+from starlette.middleware.base import BaseHTTPMiddleware+from starlette.types import ASGIApp, Message, Scope++from free_claude_code.api.request_ids import (+ RequestCorrelationMiddleware,+ get_request_id,+)+from tests.api.support import create_test_app+++def _http_scope(path: str) -> Scope:+ return cast(+ Scope,+ {+ "type": "http",+ "asgi": {"version": "3.0", "spec_version": "2.4"},+ "http_version": "1.1",+ "method": "POST",+ "scheme": "http",+ "path": path,+ "raw_path": path.encode(),+ "query_string": b"",+ "headers": [(b"anthropic-session-id", b"session_test")],+ "client": None,+ "server": None,+ },+ )+++def test_application_uses_the_pure_asgi_correlation_owner() -> None:+ app = create_test_app()+ middleware_classes = [middleware.cls for middleware in app.user_middleware]++ assert sum(cls is RequestCorrelationMiddleware for cls in middleware_classes) == 1+ assert all(cls is not BaseHTTPMiddleware for cls in middleware_classes)+++async def test_correlation_context_and_headers_span_the_complete_stream() -> None:+ response_started = asyncio.Event()+ allow_body = asyncio.Event()+ sent: list[Message] = []+ context_entries: list[dict[str, object]] = []+ context_exits: list[dict[str, object]] = []+ app_request_id: str | None = None++ async def app(scope: Scope, _receive, send) -> None:+ nonlocal app_request_id+ app_request_id = get_request_id(Request(scope))+ await send(+ {+ "type": "http.response.start",+ "status": 200,+ "headers": [],+ }+ )+ response_started.set()+ await allow_body.wait()+ await send(+ {+ "type": "http.response.body",+ "body": b"done",+ "more_body": False,+ }+ )++ @contextmanager+ def contextualize(**fields: object) -> Iterator[None]:+ context_entries.append(fields)+ try:+ yield+ finally:+ context_exits.append(fields)++ async def receive() -> Message:+ raise AssertionError("Test application does not receive messages")++ async def send(message: Message) -> None:+ sent.append(message)++ middleware = RequestCorrelationMiddleware(cast(ASGIApp, app))+ with patch(+ "free_claude_code.api.request_ids.logger.contextualize",+ side_effect=contextualize,+ ):+ request = asyncio.create_task(+ middleware(_http_scope("/v1/responses"), receive, send)+ )+ await response_started.wait()++ assert context_exits == []+ assert app_request_id is not None+ headers = Headers(raw=sent[0]["headers"])+ assert headers["request-id"] == app_request_id+ assert headers["x-request-id"] == app_request_id+ assert context_entries == [+ {+ "http_method": "POST",+ "http_path": "/v1/responses",+ "claude_session_id": "session_test",+ "request_id": app_request_id,+ }+ ]++ allow_body.set()+ await request++ assert context_exits == context_entries+++async def test_correlation_middleware_passes_non_http_scopes_unchanged() -> None:+ observed_scope: Scope | None = None++ async def app(scope: Scope, _receive, _send) -> None:+ nonlocal observed_scope+ observed_scope = scope++ async def receive() -> Message:+ return {"type": "lifespan.startup"}++ async def send(_message: Message) -> None:+ return None++ scope = cast(Scope, {"type": "lifespan", "asgi": {"version": "3.0"}})+ await RequestCorrelationMiddleware(cast(ASGIApp, app))(scope, receive, send)++ assert observed_scope is scope+ assert "state" not in scopediff --git a/tests/api/test_response_streams.py b/tests/api/test_response_streams.pyindex 56e0c10e..ce71e688 100644--- a/tests/api/test_response_streams.py+++ b/tests/api/test_response_streams.py@@ -3,13 +3,16 @@import asyncioimport jsonfrom collections.abc import AsyncGenerator-from typing import cast-from unittest.mock import AsyncMock+from typing import Any, cast+from unittest.mock import AsyncMock, patchimport pytestfrom fastapi.responses import JSONResponse, StreamingResponse+from starlette.types import Message, Scope+from free_claude_code.api.request_ids import RequestCorrelationMiddlewarefrom free_claude_code.api.response_streams import (+ ManagedStreamingResponse,anthropic_sse_streaming_response,bind_response_lifetime,terminal_execution_error_response,@@ -63,6 +66,42 @@ async def _drain(response: StreamingResponse) -> str:return "".join(parts)+def _http_scope() -> Scope:+ return cast(+ Scope,+ {+ "type": "http",+ "asgi": {"version": "3.0", "spec_version": "2.4"},+ "http_version": "1.1",+ "method": "POST",+ "scheme": "http",+ "path": "/v1/messages",+ "raw_path": b"/v1/messages",+ "query_string": b"",+ "headers": [],+ "client": None,+ "server": None,+ },+ )+++async def _serve(+ response: StreamingResponse,+ *,+ send: Any | None = None,+) -> list[Message]:+ messages: list[Message] = []++ async def receive() -> Message:+ raise AssertionError("ASGI spec 2.4 responses must not read receive")++ async def collect(message: Message) -> None:+ messages.append(message)++ await response(_http_scope(), receive, send or collect)+ return messages++@pytest.mark.asyncioasync def test_anthropic_response_waits_for_first_chunk_before_returning() -> None:ready = asyncio.Event()@@ -111,6 +150,33 @@ async def test_anthropic_pre_start_provider_error_returns_non_200_json() -> Noneassert body["error"]["message"] == "provider says slow down"+async def test_pre_start_failure_closes_body_before_response_release() -> None:+ lifecycle: list[str] = []++ class FailingBody:+ def __aiter__(self):+ return self++ async def __anext__(self) -> str:+ raise RuntimeError("provider failed")++ async def aclose(self) -> None:+ lifecycle.append("body_closed")++ async def release() -> None:+ lifecycle.append("lease_released")++ response = await anthropic_sse_streaming_response(+ FailingBody(),+ pre_start_error_response=_json_error,+ request_id="req_pre_start_order",+ )+ await bind_response_lifetime(response, release)++ assert lifecycle == ["body_closed", "lease_released"]++@pytest.mark.asyncioasync def test_terminal_execution_error_response_disables_client_retry() -> None:response = terminal_execution_error_response(@@ -160,29 +226,54 @@ async def test_non_streaming_response_releases_resource_before_return() -> None:release.assert_awaited_once()+async def test_unmanaged_stream_is_closed_and_released_before_rejection() -> None:+ release = AsyncMock()+ close = AsyncMock()++ class Body:+ def __aiter__(self):+ return self++ async def __anext__(self) -> str:+ return "unreachable"++ async def aclose(self) -> None:+ await close()++ response = StreamingResponse(Body())++ with pytest.raises(TypeError, match="ManagedStreamingResponse"):+ await bind_response_lifetime(response, release)++ close.assert_awaited_once()+ release.assert_awaited_once()++@pytest.mark.asyncioasync def test_streaming_response_releases_after_normal_completion() -> None:release = AsyncMock()- response = StreamingResponse(_body_chunks(["one", "two"]))+ response = ManagedStreamingResponse(_body_chunks(["one", "two"]))result = await bind_response_lifetime(response, release)assert result is responserelease.assert_not_awaited()- assert await _drain(response) == "onetwo"+ messages = await _serve(response)+ assert b"".join(message.get("body", b"") for message in messages) == b"onetwo"release.assert_awaited_once()@pytest.mark.asyncioasync def test_streaming_response_releases_after_body_failure() -> None:release = AsyncMock()- response = StreamingResponse(+ response = ManagedStreamingResponse(_body_then_raises(["one"], RuntimeError("stream failed")))await bind_response_lifetime(response, release)with pytest.raises(RuntimeError, match="stream failed"):- await _drain(response)+ await _serve(response)release.assert_awaited_once()@@ -195,23 +286,26 @@ async def test_streaming_response_releases_when_consumer_closes_early() -> None:async def body() -> AsyncGenerator[str]:try:yield "one"- await asyncio.Event().wait()+ yield "two"finally:source_closed.set()- response = StreamingResponse(body())- await bind_response_lifetime(response, release)- iterator = cast(- AsyncGenerator[str],- response.body_iterator.__aiter__(),+ response = await anthropic_sse_streaming_response(+ body(),+ pre_start_error_response=_json_error,+ request_id="req_test",)+ assert isinstance(response, ManagedStreamingResponse)+ await bind_response_lifetime(response, release)- assert await anext(iterator) == "one"- await iterator.aclose()+ await response.aclose()assert source_closed.is_set()release.assert_awaited_once()+ await response.aclose()+ release.assert_awaited_once()+@pytest.mark.asyncioasync def test_streaming_response_releases_when_consumer_is_cancelled() -> None:@@ -227,9 +321,9 @@ async def test_streaming_response_releases_when_consumer_is_cancelled() -> None:finally:source_closed.set()- response = StreamingResponse(body())+ response = ManagedStreamingResponse(body())await bind_response_lifetime(response, release)- drain_task = asyncio.create_task(_drain(response))+ drain_task = asyncio.create_task(_serve(response))await entered.wait()drain_task.cancel()@@ -238,3 +332,316 @@ async def test_streaming_response_releases_when_consumer_is_cancelled() -> None:assert source_closed.is_set()release.assert_awaited_once()+++async def test_response_start_send_failure_closes_prefetched_tail_and_releases() -> (+ None+):+ release = AsyncMock()+ source_closed = asyncio.Event()++ async def body() -> AsyncGenerator[str]:+ try:+ yield "prefetched"+ yield "tail"+ finally:+ source_closed.set()++ response = await anthropic_sse_streaming_response(+ body(),+ pre_start_error_response=_json_error,+ request_id="req_test",+ )+ assert isinstance(response, ManagedStreamingResponse)+ await bind_response_lifetime(response, release)++ async def fail_on_start(message: Message) -> None:+ assert message["type"] == "http.response.start"+ raise RuntimeError("send start failed")++ with pytest.raises(RuntimeError, match="send start failed"):+ await _serve(response, send=fail_on_start)++ assert source_closed.is_set()+ release.assert_awaited_once()+++async def test_first_body_send_failure_closes_prefetched_tail_and_releases() -> None:+ release = AsyncMock()+ source_closed = asyncio.Event()++ async def body() -> AsyncGenerator[str]:+ try:+ yield "prefetched"+ yield "tail"+ finally:+ source_closed.set()++ response = await anthropic_sse_streaming_response(+ body(),+ pre_start_error_response=_json_error,+ request_id="req_test",+ )+ assert isinstance(response, ManagedStreamingResponse)+ await bind_response_lifetime(response, release)++ async def fail_on_first_body(message: Message) -> None:+ if message["type"] == "http.response.body":+ raise RuntimeError("send body failed")++ with pytest.raises(RuntimeError, match="send body failed"):+ await _serve(response, send=fail_on_first_body)++ assert source_closed.is_set()+ release.assert_awaited_once()+++async def test_asgi_23_correlation_boundary_preserves_response_start_cleanup() -> None:+ release = AsyncMock()+ source_closed = asyncio.Event()++ async def body() -> AsyncGenerator[str]:+ try:+ yield "prefetched"+ yield "tail"+ finally:+ source_closed.set()++ response = await anthropic_sse_streaming_response(+ body(),+ pre_start_error_response=_json_error,+ request_id="req_test",+ )+ assert isinstance(response, ManagedStreamingResponse)+ await bind_response_lifetime(response, release)++ async def app(scope, receive, send) -> None:+ await response(scope, receive, send)++ async def receive() -> Message:+ await asyncio.Event().wait()+ raise AssertionError("unreachable")++ async def fail_on_start(message: Message) -> None:+ assert message["type"] == "http.response.start"+ raise OSError("client disconnected")++ scope = _http_scope()+ scope["asgi"]["spec_version"] = "2.3"++ with pytest.raises(OSError, match="client disconnected"):+ await RequestCorrelationMiddleware(app)(scope, receive, fail_on_start)++ assert source_closed.is_set()+ release.assert_awaited_once()+++async def test_first_body_source_failure_releases_response_lifetime() -> None:+ release = AsyncMock()+ response = ManagedStreamingResponse(_body_raises(RuntimeError("source failed")))+ await bind_response_lifetime(response, release)++ with pytest.raises(RuntimeError, match="source failed"):+ await _serve(response)++ release.assert_awaited_once()+++async def test_repeated_cancellation_waits_for_close_and_release_completion() -> None:+ close_started = asyncio.Event()+ allow_close = asyncio.Event()+ close_finished = asyncio.Event()+ release_started = asyncio.Event()+ allow_release = asyncio.Event()+ release_finished = asyncio.Event()++ class GatedBody:+ def __aiter__(self):+ return self++ async def __anext__(self) -> str:+ raise StopAsyncIteration++ async def aclose(self) -> None:+ close_started.set()+ await allow_close.wait()+ close_finished.set()++ async def release() -> None:+ release_started.set()+ await allow_release.wait()+ release_finished.set()++ response = ManagedStreamingResponse(GatedBody())+ await bind_response_lifetime(response, release)+ closing = asyncio.create_task(response.aclose())+ await close_started.wait()++ closing.cancel()+ allow_close.set()+ await release_started.wait()+ closing.cancel()+ allow_release.set()++ with pytest.raises(asyncio.CancelledError):+ await closing++ assert close_finished.is_set()+ assert release_finished.is_set()+++async def test_repeated_pre_start_cancellation_waits_for_body_close() -> None:+ iteration_started = asyncio.Event()+ close_started = asyncio.Event()+ allow_close = asyncio.Event()+ close_finished = asyncio.Event()++ class GatedPreStartBody:+ def __aiter__(self):+ return self++ async def __anext__(self) -> str:+ iteration_started.set()+ await asyncio.Event().wait()+ raise AssertionError("unreachable")++ async def aclose(self) -> None:+ close_started.set()+ await allow_close.wait()+ close_finished.set()++ response_task = asyncio.create_task(+ anthropic_sse_streaming_response(+ GatedPreStartBody(),+ pre_start_error_response=_json_error,+ request_id="req_pre_start_cancel",+ )+ )+ await iteration_started.wait()++ response_task.cancel()+ await close_started.wait()+ response_task.cancel()+ allow_close.set()++ with pytest.raises(asyncio.CancelledError):+ await response_task++ assert close_finished.is_set()+++async def test_cancellation_during_pre_start_error_cleanup_waits_for_close() -> None:+ close_started = asyncio.Event()+ allow_close = asyncio.Event()+ close_finished = asyncio.Event()++ class FailingPreStartBody:+ def __aiter__(self):+ return self++ async def __anext__(self) -> str:+ raise RuntimeError("provider failed")++ async def aclose(self) -> None:+ close_started.set()+ await allow_close.wait()+ close_finished.set()++ response_task = asyncio.create_task(+ anthropic_sse_streaming_response(+ FailingPreStartBody(),+ pre_start_error_response=_json_error,+ request_id="req_pre_start_error_cancel",+ )+ )+ await close_started.wait()++ response_task.cancel()+ allow_close.set()++ with pytest.raises(asyncio.CancelledError):+ await response_task++ assert close_finished.is_set()+++async def test_cleanup_failures_are_trace_only_and_do_not_replace_success() -> None:+ class CloseFails:+ def __init__(self) -> None:+ self._yielded = False++ def __aiter__(self):+ return self++ async def __anext__(self) -> str:+ if self._yielded:+ raise StopAsyncIteration+ self._yielded = True+ return "ok"++ async def aclose(self) -> None:+ raise RuntimeError("secret close detail")++ release = AsyncMock(side_effect=RuntimeError("secret release detail"))+ response = ManagedStreamingResponse(CloseFails())+ await bind_response_lifetime(response, release)++ with (+ patch("free_claude_code.core.trace.trace_event") as close_trace,+ patch("free_claude_code.api.response_streams.trace_event") as release_trace,+ ):+ messages = await _serve(response)++ assert b"".join(message.get("body", b"") for message in messages) == b"ok"+ close_trace.assert_called_once()+ assert close_trace.call_args.kwargs["owner"] == "ManagedStreamingResponse"+ assert close_trace.call_args.kwargs["close_exc_type"] == "RuntimeError"+ assert release_trace.call_args.kwargs["operation"] == "release_resource"+ trace_blob = " ".join(+ str(call)+ for call in [*close_trace.call_args_list, *release_trace.call_args_list]+ )+ assert "secret close detail" not in trace_blob+ assert "secret release detail" not in trace_blob+++async def test_body_close_cancellation_propagates_without_releasing() -> None:+ class CloseIsCancelled:+ def __aiter__(self):+ return self++ async def __anext__(self) -> str:+ raise StopAsyncIteration++ async def aclose(self) -> None:+ raise asyncio.CancelledError++ release = AsyncMock()+ response = ManagedStreamingResponse(CloseIsCancelled())+ await bind_response_lifetime(response, release)++ with pytest.raises(asyncio.CancelledError):+ await response.aclose()++ release.assert_not_awaited()+++async def test_lease_release_cancellation_propagates() -> None:+ release = AsyncMock(side_effect=asyncio.CancelledError)+ response = ManagedStreamingResponse(_body_chunks([]))+ await bind_response_lifetime(response, release)++ with pytest.raises(asyncio.CancelledError):+ await response.aclose()++ release.assert_awaited_once()diff --git a/tests/application/test_execution.py b/tests/application/test_execution.pyindex 7922a804..aa77e5d4 100644--- a/tests/application/test_execution.py+++ b/tests/application/test_execution.py@@ -9,12 +9,14 @@ from free_claude_code.application.execution import ProviderExecutorfrom free_claude_code.application.routing import ResolvedModel, RoutedMessagesRequestfrom free_claude_code.config.provider_catalog import ProviderCapabilitiesfrom free_claude_code.core.anthropic.models import Message, MessagesRequest+from free_claude_code.core.async_iterators import AsyncCloseableclass FakeProvider:def __init__(self) -> None:self.preflight_calls: list[tuple[MessagesRequest, bool]] = []self.stream_calls: list[dict[str, object]] = []+ self.stream_close_calls = 0def preflight_stream(self,@@ -40,7 +42,10 @@ class FakeProvider:"thinking_enabled": thinking_enabled,})- yield "event: message_stop\ndata: {}\n\n"+ try:+ yield "event: message_stop\ndata: {}\n\n"+ finally:+ self.stream_close_calls += 1class FailingPreflightProvider(FakeProvider):@@ -53,6 +58,18 @@ class FailingPreflightProvider(FakeProvider):raise ValueError("invalid provider request")+class FailingStreamConstructionProvider(FakeProvider):+ def stream_response(+ self,+ request: MessagesRequest,+ input_tokens: int = 0,+ *,+ request_id: str | None = None,+ thinking_enabled: bool | None = None,+ ) -> AsyncIterator[str]:+ raise RuntimeError("stream construction failed")++def _routed_request() -> RoutedMessagesRequest:request = MessagesRequest(model="provider-model",@@ -99,6 +116,50 @@ async def test_executor_uses_structural_provider_port_and_preflights_eagerly() -"thinking_enabled": True,}]+ assert provider.stream_close_calls == 1+++async def test_closing_executor_stream_closes_provider_stream_once() -> None:+ provider = FakeProvider()+ routed = _routed_request()+ executor = ProviderExecutor(+ lambda _provider_id: provider,+ token_counter=lambda _messages, _system, _tools: 17,+ )+ stream = executor.stream(+ routed,+ wire_api="messages",+ raw_log_label="FULL_PAYLOAD",+ raw_log_payload={},+ request_id="req_early_close",+ )++ assert await anext(stream) == "event: message_stop\ndata: {}\n\n"+ assert isinstance(stream, AsyncCloseable)+ await stream.aclose()++ assert provider.stream_close_calls == 1+++async def test_stream_construction_failure_remains_deferred_to_iteration() -> None:+ provider = FailingStreamConstructionProvider()+ executor = ProviderExecutor(+ lambda _provider_id: provider,+ token_counter=lambda _messages, _system, _tools: 17,+ )++ stream = executor.stream(+ _routed_request(),+ wire_api="messages",+ raw_log_label="FULL_PAYLOAD",+ raw_log_payload={},+ request_id="req_deferred_construction",+ )++ with pytest.raises(RuntimeError, match="stream construction failed"):+ await anext(stream)def test_executor_preflight_failure_stays_before_token_count_and_stream() -> None:diff --git a/tests/core/openai_responses/test_sse.py b/tests/core/openai_responses/test_sse.pyindex 8d59893f..ededbfec 100644--- a/tests/core/openai_responses/test_sse.py+++ b/tests/core/openai_responses/test_sse.py@@ -1,19 +1,57 @@from collections.abc import AsyncIteratorfrom typing import Any+from unittest.mock import patchimport pytestfrom free_claude_code.core.anthropic.stream_contracts import parse_sse_textfrom free_claude_code.core.anthropic.streaming import format_sse_event+from free_claude_code.core.async_iterators import AsyncCloseablefrom free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.core.openai_responses import (OpenAIResponsesAdapter,OpenAIResponsesRequest,)+from free_claude_code.core.openai_responses.anthropic_sse import (+ AnthropicSseEvent,+ iter_sse_events,+)_ADAPTER = OpenAIResponsesAdapter()+class _CloseTrackingAsyncIterator:+ def __init__(+ self,+ values: list[Any],+ *,+ iteration_error: Exception | None = None,+ close_error: Exception | None = None,+ ) -> None:+ self._values = iter(values)+ self._iteration_error = iteration_error+ self._close_error = close_error+ self.close_calls = 0++ def __aiter__(self) -> _CloseTrackingAsyncIterator:+ return self++ async def __anext__(self) -> Any:+ try:+ return next(self._values)+ except StopIteration:+ if self._iteration_error is not None:+ error = self._iteration_error+ self._iteration_error = None+ raise error from None+ raise StopAsyncIteration from None++ async def aclose(self) -> None:+ self.close_calls += 1+ if self._close_error is not None:+ raise self._close_error++def _responses_sse(chunks: AsyncIterator[str], request: dict[str, Any]) -> AsyncIterator[str]:@@ -23,6 +61,107 @@ def _responses_sse()+async def test_anthropic_sse_parser_closes_source_after_normal_completion() -> None:+ source = _CloseTrackingAsyncIterator(+ [format_sse_event("message_start", {"type": "message_start"})]+ )++ events = [event async for event in iter_sse_events(source)]++ assert [event.event for event in events] == ["message_start"]+ assert source.close_calls == 1+++async def test_anthropic_sse_parser_closes_source_on_early_close() -> None:+ source = _CloseTrackingAsyncIterator(+ [+ format_sse_event("message_start", {"type": "message_start"}),+ format_sse_event("message_stop", {"type": "message_stop"}),+ ]+ )+ events = iter_sse_events(source)++ assert (await anext(events)).event == "message_start"+ assert isinstance(events, AsyncCloseable)+ await events.aclose()++ assert source.close_calls == 1+++async def test_anthropic_sse_parser_preserves_source_failure() -> None:+ source_failure = RuntimeError("source failed")+ source = _CloseTrackingAsyncIterator(+ [],+ iteration_error=source_failure,+ close_error=RuntimeError("close failed"),+ )++ with pytest.raises(RuntimeError) as exc_info:+ [event async for event in iter_sse_events(source)]++ assert exc_info.value is source_failure+ assert source.close_calls == 1+++async def test_responses_transform_closes_direct_event_source_on_early_close() -> None:+ events = _CloseTrackingAsyncIterator(+ [+ AnthropicSseEvent(+ event="message_start",+ data={"type": "message_start", "message": {}},+ ),+ AnthropicSseEvent(+ event="message_stop",+ data={"type": "message_stop"},+ ),+ ]+ )+ with patch(+ "free_claude_code.core.openai_responses.stream.iter_sse_events",+ return_value=events,+ ):+ stream = _responses_sse(+ _aiter([]),+ {"model": "nvidia_nim/test-model", "stream": True},+ )+ assert parse_sse_text(await anext(stream))[0].event == "response.created"+ assert isinstance(stream, AsyncCloseable)+ await stream.aclose()++ assert events.close_calls == 1+++async def test_responses_transform_preserves_direct_source_failure() -> None:+ source_failure = RuntimeError("event source failed")+ events = _CloseTrackingAsyncIterator(+ [],+ iteration_error=source_failure,+ close_error=RuntimeError("event close failed"),+ )+ with (+ patch(+ "free_claude_code.core.openai_responses.stream.iter_sse_events",+ return_value=events,+ ),+ pytest.raises(RuntimeError) as exc_info,+ ):+ [+ chunk+ async for chunk in _responses_sse(+ _aiter([]),+ {"model": "nvidia_nim/test-model", "stream": True},+ )+ ]++ assert exc_info.value is source_failure+ assert events.close_calls == 1++@pytest.mark.asyncioasync def test_anthropic_text_stream_converts_to_responses_sse() -> None:text = await _collect_sse(diff --git a/tests/core/test_async_iterators.py b/tests/core/test_async_iterators.pynew file mode 100644index 00000000..2a1d8250--- /dev/null+++ b/tests/core/test_async_iterators.py@@ -0,0 +1,54 @@+"""Async iterator lifecycle helper contracts."""++import asyncio++import pytest++from free_claude_code.core.async_iterators import (+ AsyncCloseable,+ try_close_async_iterator,+)+++class _Closeable:+ def __init__(self, error: BaseException | None = None) -> None:+ self._error = error+ self.close_calls = 0++ async def aclose(self) -> None:+ self.close_calls += 1+ if self._error is not None:+ raise self._error+++async def test_try_close_async_iterator_closes_supported_value_once() -> None:+ value = _Closeable()++ assert isinstance(value, AsyncCloseable)+ assert await try_close_async_iterator(value) is None+ assert value.close_calls == 1+++async def test_try_close_async_iterator_ignores_non_closeable_value() -> None:+ assert await try_close_async_iterator(object()) is None+++async def test_try_close_async_iterator_returns_ordinary_close_failure() -> None:+ failure = RuntimeError("close failed")+ value = _Closeable(failure)++ assert await try_close_async_iterator(value) is failure+ assert value.close_calls == 1+++async def test_try_close_async_iterator_propagates_cancellation() -> None:+ value = _Closeable(asyncio.CancelledError())++ with pytest.raises(asyncio.CancelledError):+ await try_close_async_iterator(value)++ assert value.close_calls == 1diff --git a/tests/core/test_trace.py b/tests/core/test_trace.pyindex cdea643a..60c0614f 100644--- a/tests/core/test_trace.py+++ b/tests/core/test_trace.py@@ -14,6 +14,38 @@ from free_claude_code.core.trace import ()+class _CloseTrackingIterator:+ def __init__(+ self,+ chunks: list[str],+ *,+ iteration_error: Exception | None = None,+ close_error: Exception | None = None,+ ) -> None:+ self._chunks = iter(chunks)+ self._iteration_error = iteration_error+ self._close_error = close_error+ self.close_calls = 0++ def __aiter__(self) -> _CloseTrackingIterator:+ return self++ async def __anext__(self) -> str:+ try:+ return next(self._chunks)+ except StopIteration:+ if self._iteration_error is not None:+ error = self._iteration_error+ self._iteration_error = None+ raise error from None+ raise StopAsyncIteration from None++ async def aclose(self) -> None:+ self.close_calls += 1+ if self._close_error is not None:+ raise self._close_error++def _json_log_rows(log_file: str) -> list[dict]:logger.complete()text = Path(log_file).read_text(encoding="utf-8").strip()@@ -52,14 +84,12 @@ async def test_traced_async_stream_logs_completion(tmp_path) -> None:log_file = str(tmp_path / "complete.log")configure_logging(log_file, force=True)- async def source():- yield "hello"- yield " world"+ source = _CloseTrackingIterator(["hello", " world"])chunks = [chunkasync for chunk in traced_async_stream(- source(),+ source,stage="egress",source="unit",complete_event="stream.completed",@@ -69,6 +99,7 @@ async def test_traced_async_stream_logs_completion(tmp_path) -> None:]assert chunks == ["hello", " world"]+ assert source.close_calls == 1rows = _json_log_rows(log_file)completed = [row for row in rows if row.get("event") == "stream.completed"]assert len(completed) == 1@@ -82,13 +113,15 @@ async def test_traced_async_stream_logs_real_exception(tmp_path) -> None:log_file = str(tmp_path / "error.log")configure_logging(log_file, force=True)- async def source():- yield "before"- raise RuntimeError("boom")+ source = _CloseTrackingIterator(+ ["before"],+ iteration_error=RuntimeError("boom"),+ close_error=RuntimeError("close boom"),+ )with pytest.raises(RuntimeError, match="boom"):async for _chunk in traced_async_stream(- source(),+ source,stage="egress",source="unit",complete_event="stream.completed",@@ -97,6 +130,8 @@ async def test_traced_async_stream_logs_real_exception(tmp_path) -> None:):pass+ assert source.close_calls == 1+rows = _json_log_rows(log_file)interrupted = [row for row in rows if row.get("event") == "stream.interrupted"]assert len(interrupted) == 1@@ -104,6 +139,13 @@ async def test_traced_async_stream_logs_real_exception(tmp_path) -> None:assert interrupted[0]["stream_chunks"] == 1assert interrupted[0]["outcome"] == "error"assert interrupted[0]["exc_type"] == "RuntimeError"+ close_failed = [+ row for row in rows if row.get("event") == "stream.input.close_failed"+ ]+ assert len(close_failed) == 1+ assert close_failed[0]["owner"] == "traced_async_stream"+ assert close_failed[0]["close_exc_type"] == "RuntimeError"+ assert close_failed[0]["preserved_exc_type"] == "RuntimeError"@pytest.mark.asyncio@@ -111,12 +153,10 @@ async def test_traced_async_stream_closes_quietly_on_generator_exit(tmp_path) ->log_file = str(tmp_path / "generator_exit.log")configure_logging(log_file, force=True)- async def source():- yield "first"- yield "second"+ source = _CloseTrackingIterator(["first", "second"])stream = traced_async_stream(- source(),+ source,stage="egress",source="unit",complete_event="stream.completed",@@ -127,6 +167,7 @@ async def test_traced_async_stream_closes_quietly_on_generator_exit(tmp_path) ->assert await anext(stream) == "first"await stream.aclose()+ assert source.close_calls == 1rows = _json_log_rows(log_file)events = {row.get("event") for row in rows}assert "stream.completed" not in eventsdiff --git a/tests/providers/test_anthropic_messages.py b/tests/providers/test_anthropic_messages.pyindex f4048948..671f2ed2 100644--- a/tests/providers/test_anthropic_messages.py+++ b/tests/providers/test_anthropic_messages.py@@ -12,6 +12,7 @@ from free_claude_code.core.anthropic.streaming import (AnthropicStreamLedger,format_sse_event,)+from free_claude_code.core.async_iterators import AsyncCloseablefrom free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.providers.base import ProviderConfigfrom free_claude_code.providers.rate_limit import ProviderRateLimiter@@ -61,18 +62,22 @@ class FakeResponse:self._raise_error = raise_error or RuntimeError("mid-stream failure")self._close_error = close_errorself.close_calls = 0+ self.line_iterator_close_calls = 0self.is_closed = Falseself.request = httpx.Request("POST", "https://example.test/v1/messages")self.headers = httpx.Headers()async def aiter_lines(self):- for i, line in enumerate(self._lines):- yield line- if (- self._raise_after_line_index is not None- and i >= self._raise_after_line_index- ):- raise self._raise_error+ try:+ for i, line in enumerate(self._lines):+ yield line+ if (+ self._raise_after_line_index is not None+ and i >= self._raise_after_line_index+ ):+ raise self._raise_error+ finally:+ self.line_iterator_close_calls += 1async def aread(self):return self._text.encode()@@ -256,6 +261,56 @@ async def test_stream_uses_retry_builds_request_and_closes_response(mock_rate_limiter.execute_with_retry.assert_awaited_once()+async def test_closing_public_native_stream_closes_response_once(+ provider_config,+ mock_rate_limiter,+):+ provider = NativeProvider(provider_config, rate_limiter=mock_rate_limiter)+ request = make_messages_request()+ response = FakeResponse(+ lines=_lines_from_events(+ format_sse_event(+ "message_start",+ {"type": "message_start", "message": {}},+ ),+ format_sse_event(+ "content_block_start",+ {+ "type": "content_block_start",+ "index": 0,+ "content_block": {"type": "text", "text": ""},+ },+ ),+ format_sse_event(+ "content_block_delta",+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {"type": "text_delta", "text": "x" * 65_536},+ },+ ),+ )+ )++ with (+ patch.object(provider._client, "build_request", return_value=MagicMock()),+ patch.object(+ provider._client,+ "send",+ new_callable=AsyncMock,+ return_value=response,+ ),+ ):+ stream = provider.stream_response(request, request_id="req_native_early_close")+ await anext(stream)+ assert isinstance(stream, AsyncCloseable)+ await stream.aclose()++ assert response.close_calls == 1+ assert response.line_iterator_close_calls == 1++@pytest.mark.asyncioasync def test_late_error_after_native_message_stop_keeps_successful_lifecycle(provider_config,diff --git a/tests/providers/test_execution_failure_boundary.py b/tests/providers/test_execution_failure_boundary.pyindex acb6ccaa..1e4c8314 100644--- a/tests/providers/test_execution_failure_boundary.py+++ b/tests/providers/test_execution_failure_boundary.py@@ -8,6 +8,7 @@ import pytestfrom free_claude_code.config.nim import NimSettingsfrom free_claude_code.core.anthropic.stream_contracts import parse_sse_text+from free_claude_code.core.async_iterators import AsyncCloseablefrom free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.providers.base import ProviderConfigfrom free_claude_code.providers.nvidia_nim import NvidiaNimProvider@@ -231,3 +232,33 @@ async def test_completed_stream_close_failure_preserves_success_lifecycle() -> Npreserved_exc_type=None,)assert "SECRET" not in repr(trace_event.call_args)+++async def test_closing_public_openai_stream_closes_raw_stream_once() -> None:+ provider = _provider()+ request = make_messages_request(+ "test-model",+ messages=[],+ max_tokens=32,+ )+ raw_stream = _FailingStream(+ [+ _chunk(content="x" * 65_536),+ _chunk(content="done", finish_reason="stop"),+ ],+ None,+ )++ with patch.object(+ provider._client.chat.completions,+ "create",+ new_callable=AsyncMock,+ return_value=raw_stream,+ ):+ stream = provider.stream_response(request, request_id="req_early_close")+ await anext(stream)+ assert isinstance(stream, AsyncCloseable)+ await stream.aclose()++ assert raw_stream.close_calls == 1diff --git a/uv.lock b/uv.lockindex 92a2efd7..b6ae57c6 100644--- a/uv.lock+++ b/uv.lock@@ -561,7 +561,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "3.5.5"+version = "3.5.6"source = { editable = "." }dependencies = [{ name = "aiohttp" },