Skip to content

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.md
index 0397ec22..906c3161 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -236,10 +236,12 @@ configures logging, constructs the runtime owners and the configured voice
the consumer-owned ports in [application/ports.py](src/free_claude_code/application/ports.py); Admin operations retain
their 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 generation
lease 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 its
single 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 use
constant-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 settings
object.
[api/response_streams.py](src/free_claude_code/api/response_streams.py) owns public streaming egress
commit 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 deterministic
preflight failures remain ordinary HTTP errors and do not receive the terminal
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 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_router
from .ports import ApiServices
from .request_errors import ordinary_application_error_response
from .request_ids import (
+ RequestCorrelationMiddleware,
attach_request_id_headers,
get_request_id,
- new_request_id,
- set_request_id,
)
from .routes import router
from .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.py
index 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 uuid
from 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_headers
REQUEST_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_id
if path in _OPENAI_REQUEST_ID_PATHS:
- response.headers[OPENAI_REQUEST_ID_HEADER] = request_id
+ headers[OPENAI_REQUEST_ID_HEADER] = request_id
diff --git a/src/free_claude_code/api/response_streams.py b/src/free_claude_code/api/response_streams.py
index 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 asyncio
from collections.abc import (
- AsyncGenerator,
- AsyncIterable,
AsyncIterator,
Awaitable,
Callable,
Mapping,
)
-from typing import Any, Literal, Protocol, runtime_checkable
+from typing import Any, Literal
from fastapi.responses import JSONResponse, Response, StreamingResponse
+from starlette.background import BackgroundTask
+from starlette.responses import ContentStream
+from starlette.types import Receive, Scope, Send
from free_claude_code.core.anthropic import anthropic_error_type_for_failure
from 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_iterator
from free_claude_code.core.diagnostics import safe_exception_message
from 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_event
TERMINAL_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 response
def 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)
raise
except 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 = True
raise
- 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_frame
if 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.py
index 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 sys
from collections.abc import AsyncIterator, Callable
from 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 ProviderResolver
from .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.py
new file mode 100644
index 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 None
diff --git a/src/free_claude_code/core/openai_responses/anthropic_sse.py b/src/free_claude_code/core/openai_responses/anthropic_sse.py
index 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 sys
from collections.abc import AsyncIterable, AsyncIterator
from dataclasses import dataclass
from 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.py
index 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 sys
from collections.abc import AsyncIterable, AsyncIterator, Callable
from typing import Any
from free_claude_code.core.diagnostics import safe_exception_message
from free_claude_code.core.failures import ExecutionFailure, find_execution_failure
+from free_claude_code.core.trace import close_stream_input
from .anthropic_sse import iter_sse_events
from .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 chunk
emitted_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.py
index 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 sys
from collections.abc import AsyncGenerator, AsyncIterator, Mapping
from typing import Any
from 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.py
index 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.py
index 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 = None
try:
response = await self._transport._rate_limiter.execute_with_retry(
self._transport._validated_stream_send,
@@ -296,11 +306,12 @@ class _AnthropicMessagesStreamRunner:
chunk_count = 0
chunk_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 += 1
chunk_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 error
finally:
+ 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_event
def _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.py
index 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.py
new file mode 100644
index 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 scope
diff --git a/tests/api/test_response_streams.py b/tests/api/test_response_streams.py
index 56e0c10e..ce71e688 100644
--- a/tests/api/test_response_streams.py
+++ b/tests/api/test_response_streams.py
@@ -3,13 +3,16 @@
import asyncio
import json
from collections.abc import AsyncGenerator
-from typing import cast
-from unittest.mock import AsyncMock
+from typing import Any, cast
+from unittest.mock import AsyncMock, patch
import pytest
from fastapi.responses import JSONResponse, StreamingResponse
+from starlette.types import Message, Scope
+from free_claude_code.api.request_ids import RequestCorrelationMiddleware
from 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.asyncio
async 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() -> None
assert 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.asyncio
async 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.asyncio
async 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 response
release.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.asyncio
async 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.asyncio
async 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.py
index 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 ProviderExecutor
from free_claude_code.application.routing import ResolvedModel, RoutedMessagesRequest
from free_claude_code.config.provider_catalog import ProviderCapabilities
from free_claude_code.core.anthropic.models import Message, MessagesRequest
+from free_claude_code.core.async_iterators import AsyncCloseable
class FakeProvider:
def __init__(self) -> None:
self.preflight_calls: list[tuple[MessagesRequest, bool]] = []
self.stream_calls: list[dict[str, object]] = []
+ self.stream_close_calls = 0
def 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 += 1
class 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.py
index 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 AsyncIterator
from typing import Any
+from unittest.mock import patch
import pytest
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.core.anthropic.streaming import format_sse_event
+from free_claude_code.core.async_iterators import AsyncCloseable
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from 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.asyncio
async 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.py
new file mode 100644
index 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 == 1
diff --git a/tests/core/test_trace.py b/tests/core/test_trace.py
index 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 = [
chunk
async 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 == 1
rows = _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"] == 1
assert 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 == 1
rows = _json_log_rows(log_file)
events = {row.get("event") for row in rows}
assert "stream.completed" not in events
diff --git a/tests/providers/test_anthropic_messages.py b/tests/providers/test_anthropic_messages.py
index 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 AsyncCloseable
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.providers.base import ProviderConfig
from 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_error
self.close_calls = 0
+ self.line_iterator_close_calls = 0
self.is_closed = False
self.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 += 1
async 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.asyncio
async 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.py
index acb6ccaa..1e4c8314 100644
--- a/tests/providers/test_execution_failure_boundary.py
+++ b/tests/providers/test_execution_failure_boundary.py
@@ -8,6 +8,7 @@ import pytest
from free_claude_code.config.nim import NimSettings
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.async_iterators import AsyncCloseable
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
@@ -231,3 +232,33 @@ async def test_completed_stream_close_failure_preserves_success_lifecycle() -> N
preserved_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 == 1
diff --git a/uv.lock b/uv.lock
index 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" },