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

Add GitHub Copilot provider and Messages egress (#1670)

Ali Khokhar4b0eef6f61a2
diff --git a/.env.example b/.env.example
index 14a08fde..4e84b9e2 100644
--- a/.env.example
+++ b/.env.example
@@ -418,3 +418,8 @@ LOG_RAW_MESSAGING_CONTENT=false
LOG_RAW_CLI_DIAGNOSTICS=false
# When true, log full exception and CLI error message strings in messaging (may leak user content).
LOG_MESSAGING_ERROR_DETAILS=false
+
+# GitHub Copilot is an Admin connected account; no FCC API-key setting is needed.
+# Install the supported Copilot CLI version documented in README.md on PATH.
+# Connect in Admin, or first sign in with: copilot login --device-code
+# FCC stores enabled state only; the native Copilot profile owns credentials.
diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index c768452e..00000000
--- a/AGENTS.md
+++ /dev/null
@@ -1,126 +0,0 @@
-# FCC Development Instructions
-
-Keep `AGENTS.md` and `CLAUDE.md` byte-for-byte identical.
-
-Free Claude Code is a local Python gateway connecting coding agents to configured
-AI providers. Read [ARCHITECTURE.md](ARCHITECTURE.md) for ownership and request
-flows, [README.md](README.md) for user workflows, and [.env.example](.env.example)
-for documented settings.
-
-## Tooling
-
-- Commands assume the repository root. Unrelated edits and untracked files are
- outside the change scope; use `git ls-files` for tracked paths and `rg` for search.
-- Use `uv` for Python environments and `uv run` for Python tools/scripts. Follow
- [.python-version](.python-version), `[tool.uv]` in [pyproject.toml](pyproject.toml),
- and [uv.lock](uv.lock). Install missing prerequisites as needed; do not upgrade
- tools or dependencies during unrelated work.
-- `uv sync --locked` prepares the development environment. Optional voice extras
- are needed only for the corresponding live transcription work.
-- Never use the real `~/.fcc/` configuration, credentials, chat database, or
- messaging state as disposable test fixtures. Use isolated temporary state.
-
-| Task | Command |
-| --- | --- |
-| Focused deterministic tests | `uv run pytest tests/<area>/test_<feature>.py -n 0 -q` |
-| Format / lint repair | `uv run ruff format <changed-paths>`; `uv run ruff check --fix <changed-paths>` |
-| Read-only format / lint checks | `uv run ruff format --check`; `uv run ruff check` |
-| Type checking | `uv run ty check` |
-| Full deterministic tests | `uv run pytest -v --tb=short` |
-| Browser setup / tests | `uv run playwright install chromium`; `uv run pytest e2e -n 0 -v --tb=short` |
-| Full local CI | Windows: `.\scripts\ci.ps1`; macOS/Linux: `./scripts/ci.sh` |
-
-Use full local CI before pushing code. The scripts run Ruff in repair mode
-before type checking and tests; review their diff. Use PowerShell
-`-Only` / `-Skip` / `-DryRun` or shell `--only` /
-`--skip` / `--dry-run` when iterating. Check IDs are `suppressions`,
-`ruff-format`, `ruff-check`, `ty`, `pytest`, and `playwright`.
-
-## Ownership And Contracts
-
-- `runtime/` composes services and owns process lifecycle and provider generations.
- `api/` owns HTTP validation, authentication, product handlers, and response
- commitment. `application/` owns routing, reasoning intent, model fallback, and
- Chat use cases. Keep these responsibilities separate.
-- `core/` owns shared protocol models/conversion, failure semantics, and redaction.
- `providers/` alone classifies SDK/HTTP failures and owns upstream attempts,
- retries, and recovery. Protocol/API boundaries choose wire errors.
-- Provider metadata belongs in `config/provider_catalog.py`; ordinary upstream
- differences belong in OpenAI Chat profiles. Add a specialized adapter only for
- behavior/state a profile cannot express. Keep provider-only settings out of
- shared `ProviderConfig`.
-- Resolve reasoning intent at the application boundary. Providers encode supported
- controls; never infer reasoning behavior from upstream model names/versions.
- Keep reasoning replay distinct from controls for the next generation.
-- Preserve each ingress protocol through the application boundary and the four
- ingress/upstream cells. Do not introduce a lossy universal request model.
- Preserve tool identity, call/result pairing, images, reasoning, usage, and
- event order; reject unrepresentable input instead of silently dropping it.
-- Preserve stream commitment and resource ownership: no model fallback after
- output commits, no duplicate terminal events, and no lease release before its
- response/stream closes. Cancellation must drain owned work; shutdown must not
- abandon partially closed resources or overlap replacement runtimes.
-- Keep config loading/provenance in `config/loader.py`, sparse Admin persistence
- in `config/admin/`, and runtime Apply in `runtime/application.py`. The managed
- `~/.fcc/.env` is the live file; repository `.env.example` is documentation.
-- Keep Chat revisions, operation settlement, and durable state consistent.
- Messaging identities include platform/chat scope; stale tasks must not revive
- cleared branches. Launchers own temporary client overlays, not native user
- credentials/configuration.
-- Follow the exact dependency/facade policy in
- [test_import_boundaries.py](tests/contracts/test_import_boundaries.py).
- Change allowed edges deliberately, never just to silence a failing contract.
-
-## Python And Design
-
-- Use Python 3.14 native annotations. Do not add
- `from __future__ import annotations`, `# type: ignore`, or `# ty: ignore`.
-- Use owner-defined types; `JsonValue`/`JsonObject` for JSON; narrowed `object`
- only at opaque boundaries. Avoid `typing.Any`; fix the underlying model.
-- Prefer top-level imports. Resolve cycles through ownership, not
- `TYPE_CHECKING` or annotation stringization. Preserve deliberate lazy loading
- at existing optional-dependency, provider-factory, and lightweight CLI owners.
-- Prefer simple composition and shared helpers over duplicated behavior or
- unnecessary base classes. Use public operations rather than another object's
- private mutable state; keep platform/provider quirks at their adapters.
-
-## Verification By Change
-
-Changed behavior needs regression coverage, including relevant failure paths.
-
-| Change | Required evidence |
-| --- | --- |
-| Protocol/provider | Relevant core/provider tests; matrix/stream contracts for conversion or event changes |
-| Routing/lifecycle/failure | Application/API/runtime tests, including fallback, disconnect, cancellation, and cleanup paths affected |
-| Settings/Admin | Config/API contracts; deterministic `e2e/` tests for changed browser interactions |
-| Chat/messaging | Persistence, revision/scope isolation, concurrency, and stop/clear tests affected |
-| CLI/install/packaging | Launcher/script/packaging contracts; relevant installed-client smoke when needed |
-| Documentation only | Source accuracy, local links, instruction-file equality, and scoped `git diff --check` |
-
-Live checks are under [smoke/](smoke/README.md), separate from deterministic CI.
-Use `FCC_LIVE_SMOKE=1` and targeted `FCC_SMOKE_TARGETS` only for the relevant
-configured services; prerequisites alone do not prove product behavior. Live
-checks can consume quota or send/delete bot messages: use only authorized
-targets and report skips or missing prerequisites accurately.
-
-GitHub's [CI workflow](.github/workflows/tests.yml) runs Ruff in check-only mode
-and enforces all six checks; failing required checks block merge. The
-dependency-cache workflow is not a validation substitute.
-
-## Versioning And Documentation
-
-Every commit merged to `main` that changes production files must include a semver
-bump in `pyproject.toml` and the matching
-`uv lock` update. Production includes all installed code/assets under
-`src/free_claude_code/` (including `runtime/`), `.env.example`, runtime/dependency/
-packaging metadata, and install/uninstall/CI scripts.
-
-Use **PATCH** for fixes/refactors/dependency or packaging updates, **MINOR** for
-backward-compatible capabilities, and **MAJOR** for breaking API/CLI/configuration
-changes. Docs, tests, smoke tests, and repository workflow changes alone do not
-require a bump.
-
-Update `ARCHITECTURE.md` when ownership, public protocols, lifecycle, configuration,
-or extension paths change; update `README.md` and `.env.example` for user-facing
-setup/configuration changes. Keep volatile defaults and catalogs in their source
-owners, and keep these two instruction files concise and identical.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
deleted file mode 100644
index 1e229262..00000000
--- a/ARCHITECTURE.md
+++ /dev/null
@@ -1,524 +0,0 @@
-# Architecture
-
-Free Claude Code (FCC) is a local Python/FastAPI gateway between coding agents
-and configured AI providers. It preserves the client's public protocol while
-routing models, translating requests and streams, and managing upstream failures.
-
-This is the maintainer map. [README.md](README.md) covers installation and user
-workflows; [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md) contain identical,
-concise development instructions. Source and executable contracts define current
-behavior; provider catalogs, client version requirements, and tuning constants
-stay with their implementation owners.
-
-## Product Surfaces
-
-- **Inference API:** Anthropic Messages and streaming OpenAI Responses, model
- discovery, token counting, health checks, and task control.
-- **Server and desktop:** `fcc-server` and the Windows/macOS `fcc-desktop` shell
- run the same application and expose the local Admin UI.
-- **Client launchers:** wrappers prepare client-specific FCC routing. Claude Code,
- Pi, and Aider use Messages; Codex, OpenCode, Cline, Hermes, DeepSeek Harness,
- Grok Build, and Muse Code use Responses.
-- **Chat Sessions:** local browser conversations with persisted history,
- reasoning, model fallback, and context compaction.
-- **Messaging:** optional Discord/Telegram bridges drive managed Claude Code
- sessions, including reply branches, task control, persistence, and voice input.
-
-Installed commands and packaged assets are defined in
-[pyproject.toml](pyproject.toml). Launcher support does not imply that a client is
-also available as a messaging-managed backend.
-
-```mermaid
-flowchart LR
- Clients[Coding agents] --> API[Messages / Responses API]
- Admin[Local Admin UI] --> Runtime[Application runtime]
- ChatUI[Chat Sessions UI] --> Chat[Chat application service]
- Bots[Discord / Telegram] --> Messaging[Messaging workflow]
- Messaging --> Managed[Managed Claude CLI]
- Managed --> API
- API --> Execution[Routing and provider execution]
- Chat --> Execution
- Chat --> Store[SQLite chat store]
- Execution --> Providers[Provider adapters]
- Providers --> Upstream[Chat Completions / Responses upstreams]
- Runtime --> Chat
- Runtime --> Messaging
- Runtime --> Generations[Provider generations and model catalog]
- Generations --> Providers
-```
-
-## Package Ownership
-
-All production Python modules live under `src/free_claude_code/`.
-
-| Package | Responsibility | Allowed direct package dependencies |
-| --- | --- | --- |
-| [core](src/free_claude_code/core/) | Protocol schemas/conversion, canonical failures, diagnostics, shared primitives | None |
-| [config](src/free_claude_code/config/) | Settings, source loading, paths, provider metadata, Admin configuration | `core` |
-| [application](src/free_claude_code/application/) | Routing, reasoning intent, execution/fallback, model metadata, Chat use cases and ports | `config`, `core` |
-| [api](src/free_claude_code/api/) | HTTP adapters, authentication, product handlers, stream commitment, Admin/browser surfaces | `application`, `config`, `core` |
-| [providers](src/free_claude_code/providers/) | Provider construction, upstream I/O, discovery, admission, retries and recovery | `application`, `config`, `core` |
-| [cli](src/free_claude_code/cli/) | Server commands, desktop shell, client launchers and managed processes | `config`, `core` |
-| [messaging](src/free_claude_code/messaging/) | Platform adapters, workflow, conversation trees, rendering and voice orchestration | `core` |
-| [runtime](src/free_claude_code/runtime/) | Process composition, lifecycle, provider generations, concrete storage and cross-package wiring | All packages above |
-
-The exact exception is `cli.commands → runtime.bootstrap`: the installed server
-command must construct the application. The lightweight `cli.entrypoints`
-module handles metadata-only commands without importing the server graph.
-
-[Import-boundary contracts](tests/contracts/test_import_boundaries.py) enforce
-the package matrix, exact exception, acyclic static imports, facade ownership,
-and optional-dependency owners. External consumers use the public facades of
-`core.openai_responses`, `providers.openai_chat`, and `messaging.trees`.
-Internal modules do not import their ancestor facade. Dynamic factory loading
-also has catalog/factory synchronization checks.
-
-Optional local voice imports belong to `messaging.transcription`; NVIDIA Riva
-imports belong to `providers.nvidia_nim.voice`. They are lazy so ordinary
-installation, startup, and metadata commands do not require voice extras.
-
-## HTTP And Protocol Flow
-
-[api/app.py](src/free_claude_code/api/app.py) constructs FastAPI around an explicit
-`ApiServices` value. Runtime services are published through `app.state.services`;
-the app factory does not construct provider resources or load global settings.
-
-| Surface | Current behavior | Owner |
-| --- | --- | --- |
-| `POST /v1/messages` | Anthropic JSON response or SSE when `stream=true` | [Messages handler](src/free_claude_code/api/handlers/messages.py) |
-| `POST /v1/responses` | Responses SSE; omitted/true `stream` accepted, false rejected | [Responses handler](src/free_claude_code/api/handlers/responses.py) |
-| `POST /v1/messages/count_tokens` | Local pre-generation token estimate | [Token-count handler](src/free_claude_code/api/handlers/token_count.py) |
-| `GET /v1/models` | Claude, direct Messages, and direct Responses catalog views | [Model catalog](src/free_claude_code/api/model_catalog.py) |
-| `GET /muse-code/models` | Authenticated compatibility alias for the Responses model view | [Routes](src/free_claude_code/api/routes.py) |
-| `GET /`, `GET /health`, `POST /stop` | Status, liveness, and managed-task control; supported endpoints also expose probes | [Routes](src/free_claude_code/api/routes.py) |
-| `/admin`, `/admin/api/...` | Local configuration, provider/account operations, diagnostics | [Admin routes](src/free_claude_code/api/admin_routes.py) |
-| `/admin/chat`, `/admin/api/chat/...` | Local Chat UI, sessions, operations, preferences and event feed | [Chat routes](src/free_claude_code/api/chat_routes.py) |
-
-The inference path is:
-
-1. HTTP middleware establishes request correlation and disconnect ownership.
-2. The route acquires a provider-generation lease and builds its protocol handler.
-3. The handler validates the request and applies any protocol-specific product
- policy. `ModelRouter` resolves the public model and reasoning intent.
-4. `ProviderExecutor` uses the application-owned `ProviderPort` to preflight and
- stream the selected candidate, applying model fallback when eligible.
-5. The provider translates to its upstream transport and returns the ingress
- protocol's SSE. The API owns final HTTP/error framing; non-streaming Messages
- aggregates the same internal stream into JSON.
-6. Response finalization closes the body chain before releasing the lease.
-
-The application keeps concrete `MessagesRequest` and `OpenAIResponsesRequest`
-types. There is no universal intermediate request schema or
-Responses-to-Messages-to-Responses round trip.
-
-| Client ingress | Chat Completions upstream | Responses upstream |
-| --- | --- | --- |
-| Anthropic Messages | Anthropic-to-Chat conversion; Chat output presented as Anthropic SSE | Messages-to-Responses conversion; Responses output presented as Anthropic SSE |
-| OpenAI Responses | Direct Responses-to-Chat conversion; Chat output presented as Responses SSE | Native Responses forwarding with FCC routing/stateless-streaming policy |
-
-[core/anthropic](src/free_claude_code/core/anthropic/) owns Anthropic schemas,
-conversion, token estimation, and stream ledgers.
-[core/openai_responses](src/free_claude_code/core/openai_responses/) owns direct
-Responses conversion, native forwarding, and event/identity helpers.
-[Protocol-matrix tests](tests/contracts/test_protocol_matrix.py) exercise all
-four cells; [stream contracts](tests/contracts/test_stream_contracts.py) protect
-public event lifecycles.
-
-Translation preserves message order, tool declarations and call/result pairing,
-images, reasoning replay, public model identity, and usage semantics. Tool-name
-encoding is reversible and belongs to
-[core/openai_tool_names.py](src/free_claude_code/core/openai_tool_names.py).
-Rich tool results are translated into target-representable content while keeping
-their call association. Unsupported cross-protocol input, such as an image
-represented only by an upstream file ID, is rejected rather than silently lost.
-Native Responses forwarding preserves upstream item/call IDs, event order,
-extensions, and usage within FCC's supported streaming contract.
-
-## Routing, Reasoning, And Failures
-
-[ModelRouter](src/free_claude_code/application/routing.py) accepts direct
-`provider/model` references, encoded gateway IDs, and Claude-family names.
-Family overrides fall back to `MODEL`; `MODEL_FALLBACKS` supplies ordered
-alternate targets. Routed requests carry the upstream model separately from the
-original public model. A fallback on the same provider is valid if it selects a
-different model.
-
-[application/reasoning.py](src/free_claude_code/application/reasoning.py) combines
-client input and configured preferences into the immutable
-[ReasoningPolicy](src/free_claude_code/core/reasoning.py): control, named effort,
-and an optional exact token budget. Providers translate documented capabilities;
-they do not parse upstream model names or versions to select reasoning behavior.
-History replay is independent of the next generation's compute controls.
-Output limits are not reasoning budgets. Discovered thinking support informs
-model presentation, not request-policy inference.
-
-Failure ownership is deliberately split:
-
-| Owner | Decision |
-| --- | --- |
-| [core/failures.py](src/free_claude_code/core/failures.py), [core/diagnostics.py](src/free_claude_code/core/diagnostics.py) | Canonical `ExecutionFailure` semantics and safe diagnostics, without transport SDKs |
-| [Provider failure policy](src/free_claude_code/providers/failure_policy.py) and specialized adapters | Classify upstream SDK/HTTP errors and qualify retries |
-| [Admission](src/free_claude_code/providers/admission.py) and [stream recovery](src/free_claude_code/providers/stream_recovery.py) | Physical attempt budget, coordinated admission/recovery, replay/continuation and commit holdback |
-| [ProviderExecutor](src/free_claude_code/application/execution.py) | Ordered model fallback and provider-progress deadline |
-| [API response streams](src/free_claude_code/api/response_streams.py) and protocol serializers | HTTP commitment and terminal error serialization |
-
-An executor candidate may advance on a canonical `ExecutionFailure` before its
-first non-empty protocol chunk. It closes the abandoned stream and opens the
-next target with a fresh request copy, retaining public identity and reasoning.
-Provider-local `retryable` metadata does not govern this model transition.
-Once a candidate emits output, fallback stops. Ordinary validation errors,
-unexpected exceptions, cancellation, and the application progress deadline do
-not become additional model retries.
-
-`PROVIDER_PROGRESS_TIMEOUT` bounds waiting for non-empty provider output,
-including admission, retries and fallback. Changing attempts/candidates does not
-reset the current wait; emitted output renews it. Downstream backpressure is
-outside that timer. Provider HTTP timeouts and client deadlines remain separate.
-
-Before HTTP commitment, final inference failures can use non-2xx JSON; after
-commitment they must terminate the existing protocol lifecycle. Messages emits
-an Anthropic error event; Responses uses `response.failed` with the existing
-response ID. Pre-commit execution-error responses include
-`x-should-retry: false`. Providers raise canonical failures rather than invent
-client error envelopes. Context-window exhaustion is a canonical failure kind;
-the Anthropic serializer owns Claude's compaction-trigger wording.
-
-See [execution failure contracts](tests/api/test_execution_failure_contract.py),
-[model fallback tests](tests/api/test_model_fallback.py), and
-[request lifetime tests](tests/api/test_request_lifetime.py).
-
-## Provider Construction And Discovery
-
-[config/provider_catalog.py](src/free_claude_code/config/provider_catalog.py)
-owns provider IDs, authentication/readiness metadata, endpoint defaults, setting
-references and proxy metadata. It does not import provider implementations.
-
-[providers/runtime/factory.py](src/free_claude_code/providers/runtime/factory.py)
-assigns each provider exactly one construction owner:
-
-- An immutable [OpenAI Chat profile](src/free_claude_code/providers/openai_chat/profiles.py)
- for ordinary request/reasoning/replay policy.
-- A specialized adapter for actual provider state, discovery, stream, or retry
- algorithms that profile data cannot describe.
-- An injected factory for process-lifetime dependencies, such as connected-account
- authentication.
-
-The construction-owner union must equal the catalog. Within a generation,
-[ProviderRuntime](src/free_claude_code/providers/runtime/runtime.py) lazily owns
-one provider and admission controller per provider ID.
-[ProviderConfig](src/free_claude_code/providers/base.py) contains resolved shared
-configuration; provider-specific fields remain in their adapter constructors.
-
-[OpenAIChatProvider](src/free_claude_code/providers/openai_chat/provider.py)
-implements the common Chat transport with explicit request policy, reasoning,
-tool assembly, usage and recovery collaborators.
-[OpenAIResponsesTransport](src/free_claude_code/providers/openai_responses/transport.py)
-borrows the owning provider's client/admission resources for standard Responses
-execution. It owns neither authentication nor model discovery.
-
-Specialized boundaries include
-[OpenCode catalog-selected transports](src/free_claude_code/providers/opencode/),
-[NIM tool/retry handling](src/free_claude_code/providers/nvidia_nim/),
-[shared Google wire behavior](src/free_claude_code/providers/google_openai/),
-[Vertex credentials/catalogs](src/free_claude_code/providers/vertex/), and
-[Codex subscription auth/private transport](src/free_claude_code/providers/openai_codex/).
-Codex's process-lifetime auth manager owns credentials and refresh; generation
-adapters borrow it. Public Responses conversion remains provider-neutral.
-
-Provider admission separates the generation controller, one logical execution,
-and each physical attempt. Rate/concurrency admission and coordinated recovery
-are shared within that generation. Opening, corrections, replay, continuation,
-and repair consume one logical attempt budget; SDK retries do not add a hidden
-second budget. [ProviderAttemptScope](src/free_claude_code/providers/http.py)
-retains the physical stream/resource and releases its attempt exactly once.
-Already-accepted stream recovery stays request-local.
-
-[Discovery](src/free_claude_code/providers/runtime/discovery.py) is provider-owned;
-it is not assumed to be an OpenAI `/models` request. The runtime manager owns the
-application-lifetime catalog of
-[ProviderModelInfo](src/free_claude_code/application/model_metadata.py) values.
-Startup warms referenced routing providers, then discovery fills the remaining
-configured catalog in the background. Hot replacement retains useful cached
-metadata. Catalog membership is not a prerequisite for upstream execution.
-
-[runtime/codex_catalog.py](src/free_claude_code/runtime/codex_catalog.py) projects
-the neutral inventory through the Codex launcher adapter and atomically publishes
-the managed model-catalog file. Publication failures are nonfatal; the launcher
-also synchronizes at launch. Client-side catalog caching remains client-owned.
-
-## Runtime And Resource Lifecycle
-
-[cli.commands.ServerSupervisor](src/free_claude_code/cli/commands.py) owns the
-server run/restart loop.
-[runtime/bootstrap.py](src/free_claude_code/runtime/bootstrap.py) constructs the
-provider manager, connected-account auth, Chat service/store, optional
-transcriber, `ApplicationRuntime`, `ApiServices`, and ASGI application.
-[runtime/asgi.py](src/free_claude_code/runtime/asgi.py) drives runtime startup and
-shutdown through lifespan events.
-
-The supervised `RuntimeServer` first signals `ApplicationRuntime.begin_shutdown`.
-Chat stops admitting work and finishes its observer feeds before Uvicorn drains
-HTTP connections. Chat operations can still settle and publish internally;
-storage and provider resources remain owned until lifespan cleanup completes.
-
-[runtime/provider_manager.py](src/free_claude_code/runtime/provider_manager.py)
-alone publishes, retires, and closes provider generations. Each inference request
-holds a settings/provider snapshot through a lease. Provider-only Admin Apply
-prepares a candidate, commits configuration, then publishes it for new requests.
-Existing requests finish on the retired generation, which closes after its last
-lease. Failed cleanup remains owned and retryable.
-
-[Request correlation](src/free_claude_code/api/request_ids.py) covers the full
-wire send. [Inference lifetime middleware](src/free_claude_code/api/request_lifetime.py)
-owns disconnect reception and cancels unfinished inference even before the first
-frame or during a silent stream. Response finalization closes the entire body
-chain before releasing its generation on success, failure, cancellation or send
-failure. Middleware does not use `BaseHTTPMiddleware` to proxy stream bodies.
-
-[ApplicationRuntime](src/free_claude_code/runtime/application.py) shuts down
-messaging ingress/work/delivery, Chat work/storage, transcription, providers,
-then connected-account resources. Each dependency gate must close before the
-next one is released. Failed cleanup retains the ownership graph; ASGI reports
-incomplete shutdown, and the supervisor does not start an overlapping replacement.
-The supervisor owns force-termination deadlines, not arbitrary inner cleanup
-timeouts.
-
-[cli/desktop.py](src/free_claude_code/cli/desktop.py) wraps the same supervisor.
-A process lock admits one desktop host, the native tray stays on the main thread,
-and a worker runs the server. Tray restart/quit use the shared lifecycle.
-Installation and uninstallation own only their documented managed artifacts;
-client executables and native client state have separate owners.
-
-Lifecycle behavior is covered by
-[runtime tests](tests/runtime/test_application_runtime.py),
-[supervised HTTP shutdown tests](tests/cli/test_server_shutdown.py),
-[provider-manager tests](tests/runtime/test_provider_manager.py), and
-[response-stream tests](tests/api/test_response_streams.py).
-
-## Configuration, Admin Apply, And Authentication
-
-| Owner | Contract |
-| --- | --- |
-| [settings.py](src/free_claude_code/config/settings.py) | Pure Pydantic types, defaults, normalization and cross-field validation |
-| [loader.py](src/free_claude_code/config/loader.py) | Source precedence, provenance, public settings cache |
-| [env_migrations.py](src/free_claude_code/config/env_migrations.py) | Locked, atomic consolidation of legacy configuration |
-| [paths.py](src/free_claude_code/config/paths.py) | Managed configuration, auth, logs, catalogs, Chat and messaging paths |
-| [config/admin](src/free_claude_code/config/admin/) | Catalog-driven fields, presentation, validation and sparse persistence |
-| [runtime/application.py](src/free_claude_code/runtime/application.py) | Credential checks, Apply publication/restart decisions and account operations |
-
-Retired provider references are normalized per source before validation by
-`config/model_refs.py`. Managed selections are cleared to inherit the default;
-process overrides retain their ownership. Startup atomically repairs managed
-config and current Chat model selections; Chat history retains its original model
-facts. Stale direct request IDs route to the effective default, preserving encoded
-reasoning intent. Unknown preserved config values are masked in Admin previews.
-
-Live precedence is defaults, managed `~/.fcc/.env`, then process environment.
-The deliberate exception is a non-empty managed `ANTHROPIC_AUTH_TOKEN`, which
-wins over an inherited token. Settings loading may perform the one-time legacy
-migration; after consolidation, checkout env files and `FCC_ENV_FILE` are not
-live sources. [.env.example](.env.example) is documentation only.
-
-Admin updates are sparse: omission preserves values, optional-field removal is
-explicit, and masked/blank secret submissions mean unchanged. Process-owned
-fields are shown as locked. Provider fields derive from catalog metadata;
-new settings must distinguish hot-apply, restart-required, and session-sensitive
-behavior according to their runtime owners.
-
-Apply validates prospective settings and checks edited API keys through
-[credential_validation.py](src/free_claude_code/providers/credential_validation.py).
-Checks use documented non-generating authenticated endpoints and return
-`verified`, `rejected`, or `unverified`. Proven rejection blocks Apply;
-unsupported probes and inconclusive network failures are not proof of a bad
-key. Accepted changes either replace a provider generation or follow the runtime
-restart path. Configuration readiness, live provider checks, and discovery are
-separate states.
-
-Automatic restart responses identify the old runtime instance. Admin polls the
-local status endpoint until a different running instance is ready, then reloads
-settings and retains credential warnings. A bounded reconnect failure offers a
-retry without resubmitting edits. Status allows reads from validated loopback
-origins so this also works when Apply changes the server address.
-
-Authentication is defined in
-[api/dependencies.py](src/free_claude_code/api/dependencies.py):
-
-- `PROXY_AUTH_ENABLED` controls enforcement; `ANTHROPIC_AUTH_TOKEN` is the
- retained non-empty credential. Disabling enforcement does not erase it.
-- Responses and model-list routes use bearer authorization.
-- Anthropic Messages/token-count routes accept bearer authorization or, only
- when Authorization is absent, the proxy token in `x-api-key`. An invalid
- Authorization header does not fall through to `x-api-key`.
-- Token comparison is constant-time.
-- [Admin security](src/free_claude_code/api/admin_security.py) independently
- requires a loopback client, local Host authority, and a local Origin when
- supplied. It covers configuration and Chat surfaces.
-
-See [config tests](tests/config/), [auth tests](tests/api/test_auth.py),
-[credential tests](tests/providers/test_credential_validation.py), and
-[Admin tests](tests/api/test_admin.py).
-
-## Chat Sessions
-
-Chat is a separate local product surface that calls the shared application
-executor directly; it does not launch a coding agent or call FCC over loopback
-HTTP. The composition root injects provider-runtime and storage ports.
-
-| Owner | Responsibility |
-| --- | --- |
-| [application/chat/service.py](src/free_claude_code/application/chat/service.py) | Session commands, one active operation per session, generation/compaction, cancellation and terminal settlement |
-| [application/chat/context.py](src/free_claude_code/application/chat/context.py) | Model options, context estimation, transcript construction and compaction budgets |
-| [application/chat/events.py](src/free_claude_code/application/chat/events.py) | Bounded operation event subscriptions |
-| [application/chat/ports.py](src/free_claude_code/application/chat/ports.py) | Application-owned storage/subscription interfaces |
-| [runtime/chat_sqlite.py](src/free_claude_code/runtime/chat_sqlite.py) | SQLite implementation, transactions, revisions, schema handling and restart repair |
-| [api/chat_routes.py](src/free_claude_code/api/chat_routes.py) | Loopback HTTP commands, snapshots and SSE feed |
-| [Admin static assets](src/free_claude_code/api/admin_static/) | Browser session UI; [chat_markdown.py](src/free_claude_code/api/chat_markdown.py) renders response Markdown |
-
-Send/retry/regenerate/compact operations validate revisions and retain a provider
-lease while work runs. Chat uses the same Messages execution/fallback pipeline.
-Context handling includes proactive/manual compaction and bounded reactive
-recovery from context-window exhaustion. Mixed fallback failures do not become
-an unconditional compaction retry.
-
-Mutations and terminal publication must agree with durable state. Stop, delete,
-and shutdown retain operation ownership until settlement finishes; a late
-cancellation cannot downgrade an already committed completion. Browser event-feed
-disconnect only closes its subscription, not the active generation. Overflow
-requests a resync from authoritative snapshots.
-
-SQLite lives under `~/.fcc/chat/` with an exclusive process lock, short
-thread-backed transactions, and WAL. Startup handles supported schema state,
-removes unpublished generations, and marks visible unfinished generations
-interrupted. A storage startup failure leaves Chat unavailable while allowing
-the inference gateway to start.
-
-See [Chat service tests](tests/application/test_chat_service.py),
-[storage tests](tests/runtime/test_chat_sqlite.py),
-[Chat API tests](tests/api/test_chat_routes.py), and
-[browser tests](e2e/test_chat_sessions.py).
-
-## Client Launchers And Messaging
-
-[cli/launchers](src/free_claude_code/cli/launchers/) owns client-specific model
-projection, argument handling, credential isolation and temporary configuration.
-The shared [model catalog adapter](src/free_claude_code/cli/launchers/model_catalog.py)
-consumes direct Messages/Responses views; the API owns routable wire identity.
-Native client configuration and credentials remain client-owned. Pass-through
-commands and unsupported persistent/background modes are decided by each
-launcher and covered under [tests/cli](tests/cli/).
-
-[cli/local_http.py](src/free_claude_code/cli/local_http.py) bypasses forward
-proxies for local FCC health/catalog calls and adds FCC/loopback hosts to child
-`NO_PROXY` settings while retaining outbound proxy configuration.
-[cli/claude_env.py](src/free_claude_code/cli/claude_env.py) owns the shared Claude
-environment. Codex's launcher owns its generated catalog and command-backed proxy
-authentication.
-
-[Aider](src/free_claude_code/cli/launchers/aider.py) projects the Messages catalog
-into temporary model-settings/metadata files. Its model names use Aider's
-Anthropic transport, and the real proxy token is carried through a unique child
-environment variable. The launcher rejects route-file overrides that would
-replace its FCC overlay.
-
-Messaging follows a different path:
-
-```text
-Discord/Telegram ingress → workflow/turn intake → scoped tree queue
- → node runner → managed Claude CLI → FCC inference API
- → CLI event parser → transcript renderer → platform outbox
-```
-
-[ApplicationRuntime](src/free_claude_code/runtime/application.py) wires the
-platform, [MessagingWorkflow](src/free_claude_code/messaging/workflow.py),
-transcriber and [managed session manager](src/free_claude_code/cli/managed/manager.py).
-The platform adapters depend on SDKs; workflow code consumes normalized messages
-and platform-neutral ports.
-
-[Turn intake](src/free_claude_code/messaging/turn_intake.py) handles commands and
-admission; [node runner](src/free_claude_code/messaging/node_runner.py) owns CLI
-work; [trees](src/free_claude_code/messaging/trees/) encapsulates aggregates,
-claims, queues and task ownership. Identity includes platform and chat scope.
-Opaque execution claims prevent stale runners from mutating cleared or
-re-admitted branches. Reply references distinguish logical session ancestry from
-the exact prompt/status being replied to.
-
-Global stop, scoped clear, and reply-scoped operations have different boundaries.
-State detachment/cancellation and persistence complete before best-effort platform
-deletion; platform failures never restore cleared state.
-[Session persistence](src/free_claude_code/messaging/session/) uses typed
-snapshots and serialized atomic writes. Explicit flush failures remain retryable.
-
-[Platform outbox](src/free_claude_code/messaging/platforms/outbox.py) owns queued
-delivery with the runtime's limiter.
-[Voice flow](src/free_claude_code/messaging/platforms/voice_flow.py) and
-[voice claims](src/free_claude_code/messaging/voice.py) own transcription handoff,
-scoped cancellation and temporary-file cleanup. Thread-backed transcription must
-finish before its resources are released. Bootstrap selects local Whisper or the
-NIM transcriber; messaging never constructs provider adapters.
-
-See [messaging tests](tests/messaging/) for scope, reply-tree, persistence, voice,
-delivery and shutdown contracts.
-
-## Local Tools And Diagnostics
-
-[Messages optimizations](src/free_claude_code/api/optimization_handlers.py) handle
-configured quota probes, command-prefix detection, titles, suggestions and
-filepaths locally. Claude safety-classifier handling is a Messages routing policy:
-it adjusts recognized classifier requests and reasoning; it does not fabricate
-a verdict.
-
-[api/web_tools](src/free_claude_code/api/web_tools/) owns supported Anthropic
-server-tool compatibility. Forced search/fetch can run locally; the supported
-automatic-search shape buffers a normal provider decision before emitting local
-search results. Other hosted-tool shapes are rejected before upstream execution.
-[Web-fetch egress policy](src/free_claude_code/api/web_tools/egress.py) owns allowed
-schemes and private-network restrictions.
-
-[core/trace.py](src/free_claude_code/core/trace.py) carries request correlation
-across layers; [diagnostics](src/free_claude_code/core/diagnostics.py) redacts
-credentials and bounds error detail.
-[Logging configuration](src/free_claude_code/config/logging_config.py) owns file
-rotation/retention. Raw API payloads, detailed errors and messaging content are
-opt-in diagnostics. Construction-time security/logging settings require restart
-when their existing owners cannot be updated safely.
-
-## Verification And Extension Map
-
-| Change area | Primary code | Relevant verification |
-| --- | --- | --- |
-| Provider | Catalog/settings, OpenAI Chat profile or specialized adapter, runtime factory | [Provider tests](tests/providers/), [catalog contracts](tests/contracts/test_provider_catalog_order.py), targeted provider smoke |
-| Protocol | `core/anthropic`, `core/openai_responses`, transport presenters | [Protocol matrix](tests/contracts/test_protocol_matrix.py), [stream contracts](tests/contracts/test_stream_contracts.py), API failure/response tests |
-| Setting/Admin | Settings, catalog/generated manifest, Apply owner, browser assets | [Config](tests/config/), [Admin API](tests/api/test_admin.py), [e2e](e2e/) |
-| Chat | Application service/context/ports, SQLite, Chat routes/assets | [Application](tests/application/), [SQLite](tests/runtime/test_chat_sqlite.py), [Chat e2e](e2e/test_chat_sessions.py) |
-| Client/install | Launcher/config projection, entrypoints, installer/uninstaller | [CLI](tests/cli/), [scripts](tests/scripts/), [packaging](tests/contracts/test_packaging_contracts.py) |
-| Messaging | Platform ports, workflow/trees, runner/rendering, persistence | [Messaging](tests/messaging/), targeted product smoke |
-| Lifecycle | Runtime, provider manager, HTTP lifetime/response owner | [Runtime](tests/runtime/), [request lifetime](tests/api/test_request_lifetime.py), [response streams](tests/api/test_response_streams.py) |
-
-New provider settings feed the catalog-driven Admin manifest where possible.
-New clients need launcher/packaging coverage; messaging-managed support is a
-separate integration. Shared protocol behavior belongs in core, while provider
-quirks stay with their adapter. New imports must satisfy the dependency contract.
-Tests protect user behavior and ownership invariants, not obsolete internal
-module layouts.
-
-[tests](tests/) is the deterministic suite.
-[e2e](e2e/) runs real browser interactions against isolated local state and fake
-providers. [smoke](smoke/README.md) separates prerequisite probes from product
-scenarios and documents live-service opt-ins; a liveness probe is not proof that
-a complete client/tool workflow works.
-
-Runtime release identity comes from installed distribution metadata through
-[core/version.py](src/free_claude_code/core/version.py), not by parsing project
-files or duplicating version literals.
-
-Local CI is [scripts/ci.ps1](scripts/ci.ps1) on Windows or
-[scripts/ci.sh](scripts/ci.sh) on macOS/Linux. Both cover suppression policy,
-Ruff formatting/lint, ty, pytest and Playwright. Local Ruff runs repair code;
-[GitHub CI](.github/workflows/tests.yml) runs check-only Ruff and requires all
-six checks. See [AGENTS.md](AGENTS.md) for commands and subset/dry-run flags.
-The trusted dependency-cache workflow populates caches, not validation results.
-
-Update this map when public surfaces, package boundaries, ownership, lifecycle,
-configuration or extension paths change. Documentation-only updates need source
-accuracy/link checks and do not require a release bump; production changes follow
-the versioning rules in the identical instruction files.
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index c768452e..00000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,126 +0,0 @@
-# FCC Development Instructions
-
-Keep `AGENTS.md` and `CLAUDE.md` byte-for-byte identical.
-
-Free Claude Code is a local Python gateway connecting coding agents to configured
-AI providers. Read [ARCHITECTURE.md](ARCHITECTURE.md) for ownership and request
-flows, [README.md](README.md) for user workflows, and [.env.example](.env.example)
-for documented settings.
-
-## Tooling
-
-- Commands assume the repository root. Unrelated edits and untracked files are
- outside the change scope; use `git ls-files` for tracked paths and `rg` for search.
-- Use `uv` for Python environments and `uv run` for Python tools/scripts. Follow
- [.python-version](.python-version), `[tool.uv]` in [pyproject.toml](pyproject.toml),
- and [uv.lock](uv.lock). Install missing prerequisites as needed; do not upgrade
- tools or dependencies during unrelated work.
-- `uv sync --locked` prepares the development environment. Optional voice extras
- are needed only for the corresponding live transcription work.
-- Never use the real `~/.fcc/` configuration, credentials, chat database, or
- messaging state as disposable test fixtures. Use isolated temporary state.
-
-| Task | Command |
-| --- | --- |
-| Focused deterministic tests | `uv run pytest tests/<area>/test_<feature>.py -n 0 -q` |
-| Format / lint repair | `uv run ruff format <changed-paths>`; `uv run ruff check --fix <changed-paths>` |
-| Read-only format / lint checks | `uv run ruff format --check`; `uv run ruff check` |
-| Type checking | `uv run ty check` |
-| Full deterministic tests | `uv run pytest -v --tb=short` |
-| Browser setup / tests | `uv run playwright install chromium`; `uv run pytest e2e -n 0 -v --tb=short` |
-| Full local CI | Windows: `.\scripts\ci.ps1`; macOS/Linux: `./scripts/ci.sh` |
-
-Use full local CI before pushing code. The scripts run Ruff in repair mode
-before type checking and tests; review their diff. Use PowerShell
-`-Only` / `-Skip` / `-DryRun` or shell `--only` /
-`--skip` / `--dry-run` when iterating. Check IDs are `suppressions`,
-`ruff-format`, `ruff-check`, `ty`, `pytest`, and `playwright`.
-
-## Ownership And Contracts
-
-- `runtime/` composes services and owns process lifecycle and provider generations.
- `api/` owns HTTP validation, authentication, product handlers, and response
- commitment. `application/` owns routing, reasoning intent, model fallback, and
- Chat use cases. Keep these responsibilities separate.
-- `core/` owns shared protocol models/conversion, failure semantics, and redaction.
- `providers/` alone classifies SDK/HTTP failures and owns upstream attempts,
- retries, and recovery. Protocol/API boundaries choose wire errors.
-- Provider metadata belongs in `config/provider_catalog.py`; ordinary upstream
- differences belong in OpenAI Chat profiles. Add a specialized adapter only for
- behavior/state a profile cannot express. Keep provider-only settings out of
- shared `ProviderConfig`.
-- Resolve reasoning intent at the application boundary. Providers encode supported
- controls; never infer reasoning behavior from upstream model names/versions.
- Keep reasoning replay distinct from controls for the next generation.
-- Preserve each ingress protocol through the application boundary and the four
- ingress/upstream cells. Do not introduce a lossy universal request model.
- Preserve tool identity, call/result pairing, images, reasoning, usage, and
- event order; reject unrepresentable input instead of silently dropping it.
-- Preserve stream commitment and resource ownership: no model fallback after
- output commits, no duplicate terminal events, and no lease release before its
- response/stream closes. Cancellation must drain owned work; shutdown must not
- abandon partially closed resources or overlap replacement runtimes.
-- Keep config loading/provenance in `config/loader.py`, sparse Admin persistence
- in `config/admin/`, and runtime Apply in `runtime/application.py`. The managed
- `~/.fcc/.env` is the live file; repository `.env.example` is documentation.
-- Keep Chat revisions, operation settlement, and durable state consistent.
- Messaging identities include platform/chat scope; stale tasks must not revive
- cleared branches. Launchers own temporary client overlays, not native user
- credentials/configuration.
-- Follow the exact dependency/facade policy in
- [test_import_boundaries.py](tests/contracts/test_import_boundaries.py).
- Change allowed edges deliberately, never just to silence a failing contract.
-
-## Python And Design
-
-- Use Python 3.14 native annotations. Do not add
- `from __future__ import annotations`, `# type: ignore`, or `# ty: ignore`.
-- Use owner-defined types; `JsonValue`/`JsonObject` for JSON; narrowed `object`
- only at opaque boundaries. Avoid `typing.Any`; fix the underlying model.
-- Prefer top-level imports. Resolve cycles through ownership, not
- `TYPE_CHECKING` or annotation stringization. Preserve deliberate lazy loading
- at existing optional-dependency, provider-factory, and lightweight CLI owners.
-- Prefer simple composition and shared helpers over duplicated behavior or
- unnecessary base classes. Use public operations rather than another object's
- private mutable state; keep platform/provider quirks at their adapters.
-
-## Verification By Change
-
-Changed behavior needs regression coverage, including relevant failure paths.
-
-| Change | Required evidence |
-| --- | --- |
-| Protocol/provider | Relevant core/provider tests; matrix/stream contracts for conversion or event changes |
-| Routing/lifecycle/failure | Application/API/runtime tests, including fallback, disconnect, cancellation, and cleanup paths affected |
-| Settings/Admin | Config/API contracts; deterministic `e2e/` tests for changed browser interactions |
-| Chat/messaging | Persistence, revision/scope isolation, concurrency, and stop/clear tests affected |
-| CLI/install/packaging | Launcher/script/packaging contracts; relevant installed-client smoke when needed |
-| Documentation only | Source accuracy, local links, instruction-file equality, and scoped `git diff --check` |
-
-Live checks are under [smoke/](smoke/README.md), separate from deterministic CI.
-Use `FCC_LIVE_SMOKE=1` and targeted `FCC_SMOKE_TARGETS` only for the relevant
-configured services; prerequisites alone do not prove product behavior. Live
-checks can consume quota or send/delete bot messages: use only authorized
-targets and report skips or missing prerequisites accurately.
-
-GitHub's [CI workflow](.github/workflows/tests.yml) runs Ruff in check-only mode
-and enforces all six checks; failing required checks block merge. The
-dependency-cache workflow is not a validation substitute.
-
-## Versioning And Documentation
-
-Every commit merged to `main` that changes production files must include a semver
-bump in `pyproject.toml` and the matching
-`uv lock` update. Production includes all installed code/assets under
-`src/free_claude_code/` (including `runtime/`), `.env.example`, runtime/dependency/
-packaging metadata, and install/uninstall/CI scripts.
-
-Use **PATCH** for fixes/refactors/dependency or packaging updates, **MINOR** for
-backward-compatible capabilities, and **MAJOR** for breaking API/CLI/configuration
-changes. Docs, tests, smoke tests, and repository workflow changes alone do not
-require a bump.
-
-Update `ARCHITECTURE.md` when ownership, public protocols, lifecycle, configuration,
-or extension paths change; update `README.md` and `.env.example` for user-facing
-setup/configuration changes. Keep volatile defaults and catalogs in their source
-owners, and keep these two instruction files concise and identical.
diff --git a/README.md b/README.md
index fb040a92..418f76e5 100644
--- a/README.md
+++ b/README.md
@@ -188,7 +188,7 @@ from more than one provider before succeeding.
[GitHub Models retired on July 30, 2026](https://github.blog/changelog/2026-07-30-github-models-is-now-retired/). FCC automatically resets retired model
selections to your configured default, or the built-in default when `MODEL` itself
is retired. Configure that default provider in Admin if its credentials are missing.
-GitHub Copilot is a separate service and is not a replacement provider in FCC.
+GitHub Copilot is a separate service; connect it through **Connected accounts** in Admin.
| Provider | Admin UI setting | Example `MODEL` |
| --- | --- | --- |
@@ -197,6 +197,7 @@ GitHub Copilot is a separate service and is not a replacement provider in FCC.
| [Groq](https://console.groq.com/keys) | `GROQ_API_KEY` | `groq/llama-3.3-70b-versatile` |
| [ClinePass](https://docs.cline.bot/getting-started/clinepass) | `CLINE_API_KEY` | `cline_pass/cline-pass/kimi-k3` |
| [OpenAI / ChatGPT](https://learn.chatgpt.com/docs/auth) | Connect ChatGPT in the Admin UI | `openai/<model-id>` |
+| [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-sdk/auth/authenticate) | Connect GitHub Copilot in the Admin UI | `github_copilot/<model-id>` |
| [xAI (Grok)](https://console.x.ai/team/default/api-keys) | `XAI_API_KEY` | `xai/grok-4.5` |
| [QwenCloud Token Plan](https://home.qwencloud.com/api-keys) | `QWENCLOUD_API_KEY` | `qwencloud/qwen3.7-plus` |
| [QwenCloud Coding Plan](https://home.qwencloud.com/api-keys) | `QWENCLOUD_CODING_API_KEY` | `qwencloud_coding/qwen3.7-plus` |
@@ -250,6 +251,15 @@ GitHub Copilot is a separate service and is not a replacement provider in FCC.
- OpenAI uses your ChatGPT subscription rather than an API key. Connect from
**Providers → Connected accounts** in the Admin UI. Use device code on
headless systems. Restart an already-running agent after connecting.
+- GitHub Copilot uses your signed-in GitHub account and subscription. Install
+ [Copilot CLI 1.0.83](https://github.com/github/copilot-cli/releases/tag/v1.0.83)
+ on PATH, then choose **Providers → Connected accounts → GitHub Copilot → Connect**.
+ FCC reuses the native profile or shows a GitHub device code when sign-in is needed.
+ You can also sign in first with `copilot login --device-code`. Select a concrete
+ `github_copilot/<model-id>` from the discovered list; available models and quotas
+ depend on your subscription and organization policies. Restart an already-running
+ agent after connecting. Disconnect stops FCC use and leaves the native login intact.
+ FCC pins its SDK and CLI compatibility because direct endpoint access is experimental.
- Azure OpenAI uses the deployment names from your resource. Set
`AZURE_OPENAI_BASE_URL` to its complete v1 endpoint, such as
`https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/`, and select a
@@ -633,7 +643,6 @@ Windows PowerShell:
## Project Links
- [Report bugs or request features](https://github.com/Alishahryar1/free-claude-code/issues)
-- [Architecture and extension guide](ARCHITECTURE.md)
- [Contributing guide](CONTRIBUTING.md)
## License
diff --git a/e2e/conftest.py b/e2e/conftest.py
index 4d811b8b..2b278a24 100644
--- a/e2e/conftest.py
+++ b/e2e/conftest.py
@@ -2,6 +2,7 @@
import asyncio
import socket
+import sys
import threading
import time
from collections.abc import AsyncIterator, Iterator
@@ -427,9 +428,21 @@ def admin_base_url(
lifespan="on",
)
)
+
+ def run_server() -> None:
+ if sys.platform == "win32":
+ # This HTTP-only fixture owns no subprocess transports. A browser
+ # reset can interrupt Proactor socket cleanup on Python 3.14.0;
+ # use the selector loop here, leaving Playwright's loop unchanged.
+ asyncio.run(
+ server.serve(sockets=[listener]),
+ loop_factory=asyncio.SelectorEventLoop,
+ )
+ else:
+ server.run(sockets=[listener])
+
thread = threading.Thread(
- target=server.run,
- kwargs={"sockets": [listener]},
+ target=run_server,
name="fcc-admin-playwright",
daemon=True,
)
diff --git a/e2e/test_connected_accounts.py b/e2e/test_connected_accounts.py
new file mode 100644
index 00000000..11ba36a0
--- /dev/null
+++ b/e2e/test_connected_accounts.py
@@ -0,0 +1,294 @@
+"""Rendered connected-account flows use provider-owned capabilities and identity."""
+
+import pytest
+from playwright.sync_api import Dialog, Page, Route, expect
+
+from free_claude_code.application.connected_accounts import (
+ ConnectedAccountLoginMode,
+ ConnectedAccountState,
+ ConnectedAccountStatus,
+)
+from free_claude_code.core.json_types import JsonObject
+
+
+def _status(provider_id: str, *, connected: bool = False) -> JsonObject:
+ return ConnectedAccountStatus(
+ provider_id=provider_id,
+ state=(
+ ConnectedAccountState.CONNECTED
+ if connected
+ else ConnectedAccountState.DISCONNECTED
+ ),
+ connected=connected,
+ revision=1,
+ display_identity="octocat"
+ if connected and provider_id == "github_copilot"
+ else None,
+ email="[email protected]" if connected and provider_id == "openai" else None,
+ model_count=14 if connected else 0,
+ supported_login_modes=(
+ (ConnectedAccountLoginMode.DEVICE,)
+ if provider_id == "github_copilot"
+ else (ConnectedAccountLoginMode.BROWSER, ConnectedAccountLoginMode.DEVICE)
+ ),
+ default_login_mode=(
+ ConnectedAccountLoginMode.DEVICE
+ if provider_id == "github_copilot"
+ else ConnectedAccountLoginMode.BROWSER
+ ),
+ ).as_dict()
+
+
+class _Accounts:
+ def __init__(self, base_url: str) -> None:
+ self.base_url = base_url
+ self.statuses = {
+ provider_id: _status(provider_id)
+ for provider_id in ("openai", "github_copilot")
+ }
+ self.login_requests: list[tuple[str, str]] = []
+ self.cancelled: list[str] = []
+ self.disconnected: list[str] = []
+ self.hold_status: set[str] = set()
+ self.pending_status: list[Route] = []
+ self.hold_login = False
+ self.pending_login: list[Route] = []
+
+ def config(self, route: Route) -> None:
+ response = route.fetch()
+ config = response.json()
+ assert isinstance(config, dict)
+ providers = config["provider_status"]
+ assert isinstance(providers, list)
+ config["provider_status"] = [
+ provider
+ for provider in providers
+ if isinstance(provider, dict)
+ and provider.get("provider_id") not in self.statuses
+ ] + [
+ {
+ "provider_id": provider_id,
+ "display_name": name,
+ "kind": "connected_account",
+ "status": "disconnected",
+ "label": "Not connected",
+ }
+ for provider_id, name in (
+ ("openai", "OpenAI / ChatGPT"),
+ ("github_copilot", "GitHub Copilot"),
+ )
+ ]
+ route.fulfill(response=response, json=config)
+
+ def auth(self, route: Route) -> None:
+ request = route.request
+ provider_id = request.url.split("/providers/", 1)[1].split("/", 1)[0]
+ if request.method == "GET":
+ if provider_id in self.hold_status:
+ self.pending_status.append(route)
+ return
+ elif request.url.endswith("/login"):
+ payload = request.post_data_json
+ assert isinstance(payload, dict)
+ mode = payload["mode"]
+ assert isinstance(mode, str)
+ self.login_requests.append((provider_id, mode))
+ status = _status(
+ provider_id, connected=bool(self.statuses[provider_id]["connected"])
+ )
+ status.update(state="connecting", mode=mode, attempt_id="safe-test-attempt")
+ if mode == "browser":
+ status["authorization_url"] = f"{self.base_url}/account-test-sign-in"
+ else:
+ status["verification_url"] = "https://github.com/login/device"
+ status["user_code"] = "ABCD-1234"
+ self.statuses[provider_id] = status
+ if self.hold_login:
+ self.pending_login.append(route)
+ return
+ elif request.url.endswith("/cancel"):
+ self.cancelled.append(provider_id)
+ self.statuses[provider_id] = _status(provider_id)
+ elif request.method == "DELETE":
+ self.disconnected.append(provider_id)
+ self.statuses[provider_id] = _status(provider_id)
+ else:
+ raise AssertionError(f"Unexpected account operation: {request.method}")
+ route.fulfill(json=self.statuses[provider_id])
+
+
+def accounts(page: Page, admin_base_url: str) -> _Accounts:
+ result = _Accounts(admin_base_url)
+ page.route("**/admin/api/config", result.config)
+ page.route("**/admin/api/providers/*/auth**", result.auth)
+ page.context.route(
+ "**/account-test-sign-in",
+ lambda route: route.fulfill(content_type="text/html", body="Test sign-in"),
+ )
+ page.add_init_script(
+ """Object.defineProperty(navigator, 'clipboard', {
+ value: { writeText: async (text) => { window.copiedDeviceCode = text; } }
+ });"""
+ )
+ return result
+
+
+def _open(page: Page, admin_base_url: str) -> None:
+ page.goto(f"{admin_base_url}/admin")
+ expect(page.locator("#messageArea")).to_have_text("")
+
+
+def test_account_modes_wait_for_status_and_recover_after_load_failure(
+ page: Page, admin_base_url: str, accounts: _Accounts
+) -> None:
+ accounts.hold_status.add("github_copilot")
+ page.goto(f"{admin_base_url}/admin")
+ copilot = page.locator('[data-provider="github_copilot"]')
+ openai = page.locator('[data-provider="openai"]')
+ expect(copilot.get_by_role("button", name="Loading…", exact=True)).to_be_disabled()
+ expect(copilot.get_by_role("button", name="Connect", exact=True)).to_have_count(0)
+ expect(openai.get_by_role("button", name="Connect", exact=True)).to_be_enabled()
+ assert len(accounts.pending_status) == 1
+
+ accounts.pending_status.pop().fulfill(
+ status=503, json={"detail": "Account status unavailable."}
+ )
+ expect(copilot.locator(".status-pill")).to_have_text("Needs attention")
+ expect(copilot.get_by_role("button", name="Connect", exact=True)).to_have_count(0)
+ copilot.get_by_role("button", name="Retry", exact=True).click()
+ expect(copilot.get_by_role("button", name="Loading…", exact=True)).to_be_disabled()
+ assert len(accounts.pending_status) == 1
+ accounts.hold_status.clear()
+ accounts.pending_status.pop().fulfill(json=accounts.statuses["github_copilot"])
+
+ expect(copilot.get_by_role("button", name="Connect", exact=True)).to_be_enabled()
+ expect(copilot.get_by_role("button", name="Use device code")).to_have_count(0)
+ expect(openai.get_by_role("button", name="Use device code")).to_be_enabled()
+ expect(copilot.locator(".provider-meta")).to_contain_text("GitHub Copilot")
+ assert "ChatGPT" not in copilot.inner_text()
+
+
+def test_device_code_connect_copy_and_cancel_ignore_an_old_poll(
+ page: Page, admin_base_url: str, accounts: _Accounts
+) -> None:
+ _open(page, admin_base_url)
+ copilot = page.locator('[data-provider="github_copilot"]')
+ copilot.get_by_role("button", name="Connect", exact=True).click()
+ expect(copilot.locator(".provider-meta")).to_have_text(
+ "Enter code ABCD-1234 at https://github.com/login/device"
+ )
+ assert accounts.login_requests == [("github_copilot", "device")]
+ assert len(page.context.pages) == 1
+ expect(copilot.get_by_role("button", name="Open sign-in")).to_be_visible()
+ copilot.get_by_role("button", name="Copy code").click()
+ assert page.evaluate("window.copiedDeviceCode") == "ABCD-1234"
+
+ stale_status = dict(accounts.statuses["github_copilot"])
+ accounts.hold_status.add("github_copilot")
+ with page.expect_request("**/admin/api/providers/github_copilot/auth"):
+ pass
+ copilot.get_by_role("button", name="Cancel", exact=True).click()
+ expect(copilot.locator(".status-pill")).to_have_text("Not connected")
+ assert accounts.cancelled == ["github_copilot"]
+ assert len(accounts.pending_status) == 1
+ accounts.hold_status.clear()
+ with page.expect_response("**/admin/api/providers/github_copilot/auth") as response:
+ accounts.pending_status.pop().fulfill(json=stale_status)
+ response.value.finished()
+ page.evaluate("() => new Promise(requestAnimationFrame)")
+ expect(copilot.locator(".status-pill")).to_have_text("Not connected")
+ expect(copilot.get_by_role("button", name="Connect", exact=True)).to_be_enabled()
+ expect(copilot.get_by_role("button", name="Copy code")).to_have_count(0)
+
+
+def test_openai_browser_login_preopens_popup_and_retains_device_choice(
+ page: Page, admin_base_url: str, accounts: _Accounts
+) -> None:
+ accounts.hold_login = True
+ accounts.statuses["openai"] = _status("openai", connected=True)
+ _open(page, admin_base_url)
+ openai = page.locator('[data-provider="openai"]')
+ with page.expect_popup() as opened:
+ openai.get_by_role("button", name="Reconnect", exact=True).click()
+ popup = opened.value
+ try:
+ assert popup.url == "about:blank"
+ assert popup.evaluate("window.opener === null") is True
+ assert accounts.login_requests == [("openai", "browser")]
+ assert len(accounts.pending_login) == 1
+ accounts.pending_login.pop().fulfill(json=accounts.statuses["openai"])
+ popup.wait_for_url(f"{admin_base_url}/account-test-sign-in")
+ finally:
+ popup.close()
+ expect(openai.get_by_role("button", name="Cancel", exact=True)).to_be_visible()
+ expect(openai.locator(".provider-meta")).to_have_text(
+ "Finish signing in, then return to this page."
+ )
+ openai.get_by_role("button", name="Cancel", exact=True).click()
+ accounts.hold_login = False
+ openai.get_by_role("button", name="Use device code", exact=True).click()
+ expect(openai.get_by_role("button", name="Copy code")).to_be_visible()
+ assert accounts.login_requests[-1] == ("openai", "device")
+ assert len(page.context.pages) == 1
+ openai.get_by_role("button", name="Cancel", exact=True).click()
+
+
[email protected]("restart", [False, True])
+def test_connected_identities_and_modes_survive_apply_and_disconnect_independently(
+ page: Page, admin_base_url: str, accounts: _Accounts, restart: bool
+) -> None:
+ accounts.statuses = {
+ provider_id: _status(provider_id, connected=True)
+ for provider_id in accounts.statuses
+ }
+ page.route(
+ "**/admin/api/config/apply",
+ lambda route: route.fulfill(
+ json={
+ "applied": True,
+ "restart": {
+ "required": restart,
+ "automatic": restart,
+ "admin_url": "/admin",
+ "instance_id": "before-restart",
+ },
+ "credential_checks": [],
+ }
+ ),
+ )
+ page.route(
+ "**/admin/api/status",
+ lambda route: route.fulfill(
+ json={"status": "running", "instance_id": "after-restart"}
+ ),
+ )
+ _open(page, admin_base_url)
+ page.locator("#field-NVIDIA_NIM_API_KEY").fill("unused-test-key")
+ page.get_by_role("button", name="Apply", exact=True).click()
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
+ copilot = page.locator('[data-provider="github_copilot"]')
+ openai = page.locator('[data-provider="openai"]')
+ expect(copilot.locator(".provider-meta")).to_contain_text(
+ "octocat. 14 models available."
+ )
+ expect(openai.locator(".provider-meta")).to_contain_text("[email protected].")
+ expect(copilot.locator(".provider-meta")).to_contain_text("Restart your agent")
+ assert "ChatGPT" not in copilot.inner_text()
+ confirmations: list[str] = []
+
+ def accept_disconnect(dialog: Dialog) -> None:
+ confirmations.append(dialog.message)
+ dialog.accept()
+
+ page.once("dialog", accept_disconnect)
+ copilot.get_by_role("button", name="Disconnect", exact=True).click()
+ expect(copilot.locator(".status-pill")).to_have_text("Not connected")
+ assert confirmations == ["Disconnect this GitHub Copilot account from FCC?"]
+ assert accounts.disconnected == ["github_copilot"]
+ expect(openai.locator(".status-pill")).to_have_text("Connected")
+ expect(openai.locator(".provider-meta")).to_contain_text("[email protected].")
+ copilot.get_by_role("button", name="Connect", exact=True).click()
+ expect(copilot.get_by_role("button", name="Copy code")).to_be_visible()
+ assert accounts.login_requests[-1] == ("github_copilot", "device")
+ copilot.get_by_role("button", name="Cancel", exact=True).click()
diff --git a/pyproject.toml b/pyproject.toml
index 9d997480..3936bcb2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.21.1"
+version = "5.22.1"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
@@ -28,6 +28,7 @@ dependencies = [
"requests[socks]>=2.34.2",
"pystray>=0.19.5; sys_platform == 'win32' or sys_platform == 'darwin'",
"Pillow>=12.0.0; sys_platform == 'win32' or sys_platform == 'darwin'",
+ "github-copilot-sdk==1.0.13",
]
[project.scripts]
diff --git a/src/free_claude_code/api/admin_routes.py b/src/free_claude_code/api/admin_routes.py
index fbb89588..d0efb3c1 100644
--- a/src/free_claude_code/api/admin_routes.py
+++ b/src/free_claude_code/api/admin_routes.py
@@ -69,7 +69,7 @@ class AdminConfigPayload(BaseModel):
class ConnectedAccountLoginPayload(BaseModel):
"""Interactive connected-account login selection."""
- mode: ConnectedAccountLoginMode = ConnectedAccountLoginMode.BROWSER
+ mode: ConnectedAccountLoginMode | None = None
def _asset_path(filename: str) -> Path:
@@ -189,10 +189,15 @@ async def start_connected_account_login(
):
require_loopback_admin(request)
_require_connected_account_provider(provider_id)
- try:
- status = await services.admin.start_connected_account_login(
- provider_id, payload.mode
+ account = await services.admin.connected_account_status(provider_id)
+ mode = payload.mode or account.default_login_mode
+ if mode not in account.supported_login_modes:
+ raise HTTPException(
+ status_code=422,
+ detail="Login mode is not supported by this provider.",
)
+ try:
+ status = await services.admin.start_connected_account_login(provider_id, mode)
except Exception as exc:
raise HTTPException(
status_code=502,
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index 494064ba..21f7e065 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -278,7 +278,11 @@ function navigateToProviderConfiguration(provider, configuring) {
input.focus({ preventScroll: true });
}
-function renderConnectedAccountCard(provider, status = provider) {
+function connectedAccountName(provider) {
+ return provider.display_name || provider.provider_id;
+}
+
+function renderConnectedAccountCard(provider, status = null) {
const card = document.createElement("article");
card.className = "provider-card";
card.dataset.provider = provider.provider_id;
@@ -287,15 +291,15 @@ function renderConnectedAccountCard(provider, status = provider) {
const title = document.createElement("div");
title.className = "provider-title";
const name = document.createElement("strong");
- name.textContent = provider.display_name || provider.provider_id;
+ name.textContent = connectedAccountName(provider);
const pill = document.createElement("span");
- pill.className = `status-pill ${statusClass(status.state || status.status)}`;
+ pill.className = `status-pill ${statusClass(status?.state)}`;
pill.textContent = connectedAccountLabel(status);
title.append(name, pill);
const meta = document.createElement("div");
meta.className = "provider-meta";
- meta.textContent = connectedAccountMeta(status);
+ meta.textContent = connectedAccountMeta(provider, status);
const actions = document.createElement("div");
actions.className = "provider-actions";
@@ -305,35 +309,44 @@ function renderConnectedAccountCard(provider, status = provider) {
}
function connectedAccountLabel(status) {
+ if (!status) return "Loading";
const labels = {
disconnected: "Not connected",
connecting: "Connecting",
connected: "Connected",
error: "Needs attention",
};
- return labels[status.state] || status.label || "Not connected";
+ return labels[status.state] || "Not connected";
}
-function connectedAccountMeta(status) {
+function connectedAccountMeta(provider, status) {
+ if (!status) return "Checking account status…";
+ const providerName = connectedAccountName(provider);
+ if (status.state === "connecting") {
+ if (status.mode === "device" && status.user_code && status.verification_url) {
+ return `Enter code ${status.user_code} at ${status.verification_url}`;
+ }
+ return status.message || "Finish signing in, then return to this page.";
+ }
if (status.connected) {
- const identity = status.email || "ChatGPT subscription connected";
+ const identity = status.display_identity || status.email || `${providerName} account connected`;
const models = Number.isInteger(status.model_count)
? `${status.model_count} model${status.model_count === 1 ? "" : "s"} available. `
: "";
const error = status.message ? `${status.message} ` : "";
return `${identity}. ${models}${error}Restart your agent to refresh its model picker.`;
}
- if (status.mode === "device" && status.user_code) {
- return `Enter code ${status.user_code} at ${status.verification_url}`;
- }
- if (status.state === "connecting") {
- return "Finish signing in, then return to this page.";
- }
- return status.message || "Connect a ChatGPT account to discover subscription models.";
+ return status.message || `Connect your ${providerName} account to discover models.`;
}
function populateConnectedAccountActions(provider, status, actions) {
const providerId = provider.provider_id;
+ if (!status) {
+ const loading = authButton("Loading…", () => {});
+ loading.disabled = true;
+ actions.appendChild(loading);
+ return;
+ }
if (status.state === "connecting") {
const target = status.authorization_url || status.verification_url;
if (target) {
@@ -341,11 +354,7 @@ function populateConnectedAccountActions(provider, status, actions) {
}
if (status.mode === "device" && status.user_code) {
actions.appendChild(
- authButton(
- "Copy code",
- () => copyDeviceCode(status.user_code),
- "secondary-button",
- ),
+ authButton("Copy code", () => copyDeviceCode(status.user_code), "secondary-button"),
);
}
actions.appendChild(
@@ -353,30 +362,32 @@ function populateConnectedAccountActions(provider, status, actions) {
);
return;
}
- if (status.connected) {
- actions.appendChild(
- authButton(
- "Reconnect",
- (button) => startConnectedAccountLogin(providerId, "browser", button),
- ),
- );
- actions.appendChild(
- authButton(
- "Disconnect",
- () => disconnectConnectedAccount(providerId),
- "secondary-button",
- ),
- );
+ const modes = Array.isArray(status.supported_login_modes) ? status.supported_login_modes : [];
+ const defaultMode = status.default_login_mode;
+ if (!["browser", "device"].includes(defaultMode) || !modes.includes(defaultMode)) {
+ actions.appendChild(authButton("Retry", () => refreshConnectedAccount(provider)));
return;
}
actions.appendChild(
- authButton("Connect", (button) => startConnectedAccountLogin(providerId, "browser", button)),
authButton(
- "Use device code",
- (button) => startConnectedAccountLogin(providerId, "device", button),
- "secondary-button",
+ status.connected ? "Reconnect" : "Connect",
+ (button) => startConnectedAccountLogin(providerId, defaultMode, button),
),
);
+ if (status.connected) {
+ actions.appendChild(
+ authButton("Disconnect", () => disconnectConnectedAccount(providerId), "secondary-button"),
+ );
+ return;
+ }
+ modes.filter((mode) => mode !== defaultMode).forEach((mode) => {
+ const label = { browser: "Use browser", device: "Use device code" }[mode];
+ if (label) {
+ actions.appendChild(
+ authButton(label, (button) => startConnectedAccountLogin(providerId, mode, button), "secondary-button"),
+ );
+ }
+ });
}
function authButton(label, action, className = "test-button") {
@@ -392,21 +403,23 @@ async function refreshConnectedAccounts() {
const providers = (state.config?.provider_status || []).filter(
(provider) => provider.kind === "connected_account",
);
- await Promise.all(
- providers.map(async (provider) => {
- try {
- const status = await api(`/admin/api/providers/${provider.provider_id}/auth`);
- updateConnectedAccountCard(provider, status);
- if (status.state === "connecting") pollConnectedAccount(provider);
- } catch (error) {
- updateConnectedAccountCard(provider, {
- state: "error",
- connected: false,
- message: error.message,
- });
- }
- }),
- );
+ await Promise.all(providers.map(refreshConnectedAccount));
+}
+
+async function refreshConnectedAccount(provider) {
+ clearConnectedAccountPoll(provider.provider_id);
+ updateConnectedAccountCard(provider, null);
+ try {
+ const status = await api(`/admin/api/providers/${provider.provider_id}/auth`);
+ updateConnectedAccountCard(provider, status);
+ if (status.state === "connecting") pollConnectedAccount(provider);
+ } catch (error) {
+ updateConnectedAccountCard(provider, {
+ state: "error",
+ connected: false,
+ message: error.message,
+ });
+ }
}
function updateConnectedAccountCard(provider, status) {
@@ -417,8 +430,10 @@ function updateConnectedAccountCard(provider, status) {
}
async function startConnectedAccountLogin(providerId, mode, button) {
- button.disabled = true;
- const popup = window.open("about:blank", "_blank");
+ const buttons = button.closest(".provider-actions").querySelectorAll("button");
+ buttons.forEach((action) => { action.disabled = true; });
+ clearConnectedAccountPoll(providerId);
+ const popup = mode === "browser" ? window.open("about:blank", "_blank") : null;
if (popup) popup.opener = null;
try {
const status = await api(`/admin/api/providers/${providerId}/auth/login`, {
@@ -428,62 +443,79 @@ async function startConnectedAccountLogin(providerId, mode, button) {
const provider = connectedAccountDescriptor(providerId);
updateConnectedAccountCard(provider, status);
const target = status.authorization_url || status.verification_url;
- if (target && popup) {
- popup.location.replace(target);
- } else if (target) {
- window.open(target, "_blank", "noopener");
- } else if (popup) {
- popup.close();
+ if (mode === "browser") {
+ if (target && popup) {
+ popup.location.replace(target);
+ } else if (target) {
+ window.open(target, "_blank", "noopener");
+ } else if (popup) {
+ popup.close();
+ }
}
- pollConnectedAccount(provider);
+ if (status.state === "connecting") pollConnectedAccount(provider);
+ else if (status.connected) await hydrateModelOptions();
} catch (error) {
if (popup) popup.close();
showMessage(error.message, true);
- button.disabled = false;
+ buttons.forEach((action) => { action.disabled = false; });
}
}
async function cancelConnectedAccountLogin(providerId) {
clearConnectedAccountPoll(providerId);
- const status = await api(`/admin/api/providers/${providerId}/auth/cancel`, {
- method: "POST",
- });
- updateConnectedAccountCard(connectedAccountDescriptor(providerId), status);
+ const provider = connectedAccountDescriptor(providerId);
+ try {
+ const status = await api(`/admin/api/providers/${providerId}/auth/cancel`, {
+ method: "POST",
+ });
+ updateConnectedAccountCard(provider, status);
+ } catch (error) {
+ showMessage(error.message, true);
+ pollConnectedAccount(provider);
+ }
}
async function disconnectConnectedAccount(providerId) {
- if (!window.confirm("Disconnect this ChatGPT account from FCC?")) return;
+ const provider = connectedAccountDescriptor(providerId);
+ if (!window.confirm(`Disconnect this ${connectedAccountName(provider)} account from FCC?`)) return;
clearConnectedAccountPoll(providerId);
- const status = await api(`/admin/api/providers/${providerId}/auth`, {
- method: "DELETE",
- });
- updateConnectedAccountCard(connectedAccountDescriptor(providerId), status);
- await hydrateModelOptions();
+ try {
+ const status = await api(`/admin/api/providers/${providerId}/auth`, { method: "DELETE" });
+ updateConnectedAccountCard(provider, status);
+ await hydrateModelOptions();
+ } catch (error) {
+ showMessage(error.message, true);
+ }
}
function pollConnectedAccount(provider) {
- clearConnectedAccountPoll(provider.provider_id);
+ const providerId = provider.provider_id;
+ clearConnectedAccountPoll(providerId);
+ const poller = { timer: null };
+ state.authPollers.set(providerId, poller);
const poll = async () => {
try {
- const status = await api(`/admin/api/providers/${provider.provider_id}/auth`);
+ const status = await api(`/admin/api/providers/${providerId}/auth`);
+ if (state.authPollers.get(providerId) !== poller) return;
updateConnectedAccountCard(provider, status);
if (status.state === "connecting") {
- state.authPollers.set(provider.provider_id, window.setTimeout(poll, 1000));
+ poller.timer = window.setTimeout(poll, 1000);
} else {
- state.authPollers.delete(provider.provider_id);
+ state.authPollers.delete(providerId);
if (status.connected) await hydrateModelOptions();
}
} catch (error) {
- state.authPollers.delete(provider.provider_id);
+ if (state.authPollers.get(providerId) !== poller) return;
+ state.authPollers.delete(providerId);
showMessage(error.message, true);
}
};
- state.authPollers.set(provider.provider_id, window.setTimeout(poll, 1000));
+ poller.timer = window.setTimeout(poll, 1000);
}
function clearConnectedAccountPoll(providerId) {
- const timer = state.authPollers.get(providerId);
- if (timer) window.clearTimeout(timer);
+ const poller = state.authPollers.get(providerId);
+ if (poller?.timer) window.clearTimeout(poller.timer);
state.authPollers.delete(providerId);
}
diff --git a/src/free_claude_code/application/connected_accounts.py b/src/free_claude_code/application/connected_accounts.py
index 32a7c4e2..bcc9e335 100644
--- a/src/free_claude_code/application/connected_accounts.py
+++ b/src/free_claude_code/application/connected_accounts.py
@@ -40,6 +40,12 @@ class ConnectedAccountStatus:
expires_at: int | None = None
model_count: int | None = None
message: str | None = None
+ display_identity: str | None = None
+ supported_login_modes: tuple[ConnectedAccountLoginMode, ...] = (
+ ConnectedAccountLoginMode.BROWSER,
+ ConnectedAccountLoginMode.DEVICE,
+ )
+ default_login_mode: ConnectedAccountLoginMode = ConnectedAccountLoginMode.BROWSER
def as_dict(self) -> JsonObject:
"""Serialize only the explicitly safe status contract."""
@@ -49,10 +55,15 @@ class ConnectedAccountStatus:
"state": self.state,
"connected": self.connected,
"revision": self.revision,
+ "supported_login_modes": [
+ mode.value for mode in self.supported_login_modes
+ ],
+ "default_login_mode": self.default_login_mode.value,
}
optional_fields: tuple[tuple[str, JsonValue], ...] = (
("attempt_id", self.attempt_id),
("email", self.email),
+ ("display_identity", self.display_identity),
("mode", self.mode),
("authorization_url", self.authorization_url),
("verification_url", self.verification_url),
diff --git a/src/free_claude_code/config/paths.py b/src/free_claude_code/config/paths.py
index 2d6af8f7..b508b6ee 100644
--- a/src/free_claude_code/config/paths.py
+++ b/src/free_claude_code/config/paths.py
@@ -101,3 +101,8 @@ def openai_auth_lock_path() -> Path:
"""Return the cross-process lock path for ChatGPT credentials."""
return config_dir_path() / AUTH_DIRNAME / OPENAI_AUTH_LOCK_FILENAME
+
+
+def github_copilot_auth_path() -> Path:
+ """Return FCC connection state; native Copilot retains credentials."""
+ return config_dir_path() / AUTH_DIRNAME / "github_copilot.json"
diff --git a/src/free_claude_code/config/provider_catalog.py b/src/free_claude_code/config/provider_catalog.py
index a63d8bf3..357c5fe0 100644
--- a/src/free_claude_code/config/provider_catalog.py
+++ b/src/free_claude_code/config/provider_catalog.py
@@ -167,6 +167,12 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
default_base_url=OPENAI_CODEX_DEFAULT_BASE,
proxy_attr="openai_proxy",
),
+ "github_copilot": ProviderDescriptor(
+ provider_id="github_copilot",
+ display_name="GitHub Copilot",
+ auth_kind=ProviderAuthKind.CONNECTED_ACCOUNT,
+ default_base_url="https://api.githubcopilot.com",
+ ),
"xai": ProviderDescriptor(
provider_id="xai",
display_name="xAI (Grok)",
diff --git a/src/free_claude_code/core/anthropic/models.py b/src/free_claude_code/core/anthropic/models.py
index 684f8cb0..ab79bd08 100644
--- a/src/free_claude_code/core/anthropic/models.py
+++ b/src/free_claude_code/core/anthropic/models.py
@@ -2,7 +2,7 @@
from typing import Any, Literal
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
class _AnthropicBlockBase(BaseModel):
@@ -106,9 +106,12 @@ class Tool(_AnthropicBlockBase):
class ThinkingConfig(BaseModel):
+ model_config = ConfigDict(extra="allow")
+
enabled: bool | None = True
type: str | None = None
budget_tokens: int | None = None
+ display: Literal["summarized", "omitted"] | None = None
class MessagesRequest(BaseModel):
@@ -135,6 +138,13 @@ class MessagesRequest(BaseModel):
extra_body: dict[str, Any] | None = None
betas: list[str] | None = Field(default=None, exclude=True)
+ @field_validator("max_tokens", mode="before")
+ @classmethod
+ def _reject_boolean_output_limit(cls, value: object) -> object:
+ if isinstance(value, bool):
+ raise ValueError("max_tokens must not be a boolean")
+ return value
+
class TokenCountRequest(BaseModel):
model_config = ConfigDict(extra="allow")
diff --git a/src/free_claude_code/core/anthropic/native.py b/src/free_claude_code/core/anthropic/native.py
new file mode 100644
index 00000000..eb37f49c
--- /dev/null
+++ b/src/free_claude_code/core/anthropic/native.py
@@ -0,0 +1,184 @@
+"""Native Messages wire preparation, without a cross-protocol intermediate."""
+
+import json
+import re
+from collections.abc import Mapping
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import cast
+
+from free_claude_code.core.json_types import JsonObject, JsonValue
+
+from .models import MessagesRequest
+from .request_serialization import dump_messages_request
+
+_BETA_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
+_NATIVE_EXTRA_FIELDS = frozenset({"cache_control", "service_tier"})
+_RESERVED_EXTRA_FIELDS = frozenset(
+ {
+ "model",
+ "messages",
+ "system",
+ "stream",
+ "max_tokens",
+ "thinking",
+ "output_config",
+ "tools",
+ "tool_choice",
+ "betas",
+ "extra_body",
+ "original_model",
+ "resolved_provider_model",
+ "api_key",
+ "base_url",
+ "url",
+ "headers",
+ "extra_headers",
+ "authorization",
+ "anthropic-version",
+ }
+)
+
+
+class NativeMessagesError(ValueError):
+ """A request or event cannot preserve the native Messages contract."""
+
+
+@dataclass(frozen=True, slots=True)
+class NativeMessagesOptions:
+ """Provider-resolved wire controls; no model-name inference belongs here."""
+
+ model: str
+ max_tokens: int
+ thinking: JsonObject | None = None
+ output_effort: str | None = None
+
+ def __post_init__(self) -> None:
+ if not self.model.strip():
+ raise NativeMessagesError("Messages model must not be empty.")
+ if (
+ not isinstance(self.max_tokens, int)
+ or isinstance(self.max_tokens, bool)
+ or self.max_tokens <= 0
+ ):
+ raise NativeMessagesError("Messages max_tokens must be a positive integer.")
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedMessagesRequest:
+ body: JsonObject
+ betas: tuple[str, ...] = ()
+
+
+def validate_messages_json(body: JsonObject) -> None:
+ """Reject values the HTTP JSON encoder cannot send before opening an attempt."""
+
+ try:
+ json.dumps(body, ensure_ascii=False, allow_nan=False).encode("utf-8")
+ except (TypeError, ValueError, UnicodeError, RecursionError) as exc:
+ raise NativeMessagesError(
+ "Messages request must be finite JSON encodable as UTF-8."
+ ) from exc
+
+
+def apply_messages_options(body: JsonObject, options: NativeMessagesOptions) -> None:
+ """Apply resolved controls to a new body while preserving format options."""
+
+ body["model"] = options.model
+ body["max_tokens"] = options.max_tokens
+ body["stream"] = True
+ body.pop("thinking", None)
+ if options.thinking is not None:
+ body["thinking"] = deepcopy(options.thinking)
+ raw_output = body.pop("output_config", None)
+ output: JsonObject = {}
+ if raw_output is not None:
+ if not isinstance(raw_output, Mapping):
+ raise NativeMessagesError("Messages output_config must be an object.")
+ output = dict(raw_output)
+ output.pop("effort", None)
+ if options.output_effort is not None:
+ output["effort"] = options.output_effort
+ if output:
+ body["output_config"] = output
+ choice = body.get("tool_choice")
+ if (
+ options.thinking is not None
+ and options.thinking.get("type") == "enabled"
+ and isinstance(choice, Mapping)
+ and choice.get("type") in {"any", "tool"}
+ ):
+ raise NativeMessagesError(
+ "Manual Messages thinking cannot force a tool choice."
+ )
+
+
+def build_native_messages_request(
+ request: MessagesRequest, *, options: NativeMessagesOptions
+) -> PreparedMessagesRequest:
+ """Prepare native input, preserving supported nested protocol extensions."""
+
+ if not request.messages:
+ raise NativeMessagesError("Messages input must not be empty.")
+ body = cast(JsonObject, dump_messages_request(request))
+ raw_request = cast(JsonObject, request.model_dump(mode="json", exclude_none=True))
+ for name in request.model_extra or ():
+ if name not in raw_request:
+ continue
+ if name not in _NATIVE_EXTRA_FIELDS:
+ raise NativeMessagesError(
+ f"Unsupported native Messages request field: {name!r}."
+ )
+ body[name] = deepcopy(raw_request[name])
+ system: list[JsonValue] = []
+ raw_system = body.pop("system", None)
+ if isinstance(raw_system, str):
+ system.append({"type": "text", "text": raw_system})
+ elif isinstance(raw_system, list):
+ system.extend(raw_system)
+ messages: list[JsonValue] = []
+ for message in request.messages:
+ if message.reasoning_content is not None:
+ raise NativeMessagesError(
+ "Native Messages history requires signed thinking blocks; "
+ "reasoning_content cannot be replayed losslessly."
+ )
+ raw = cast(JsonObject, message.model_dump(mode="json", exclude_none=True))
+ if message.role == "system":
+ if messages:
+ raise NativeMessagesError(
+ "Native Messages supports only leading system messages."
+ )
+ content = raw["content"]
+ if isinstance(content, str):
+ system.append({"type": "text", "text": content})
+ elif isinstance(content, list):
+ if any(
+ not isinstance(block, Mapping) or block.get("type") != "text"
+ for block in content
+ ):
+ raise NativeMessagesError("System content must contain only text.")
+ system.extend(content)
+ continue
+ messages.append(raw)
+ if not messages:
+ raise NativeMessagesError("Messages input must contain a conversational turn.")
+ body["messages"] = messages
+ if system:
+ body["system"] = system
+ extra = body.pop("extra_body", None)
+ if extra is not None:
+ if not isinstance(extra, Mapping):
+ raise NativeMessagesError("Messages extra_body must be an object.")
+ for name, value in extra.items():
+ if name.lower() in _RESERVED_EXTRA_FIELDS or name in body:
+ raise NativeMessagesError(
+ f"Messages extra_body cannot override {name!r}."
+ )
+ body[name] = deepcopy(value)
+ apply_messages_options(body, options)
+ betas = tuple(request.betas or ())
+ if any(_BETA_NAME.fullmatch(beta) is None for beta in betas):
+ raise NativeMessagesError("Messages beta names must be valid header tokens.")
+ validate_messages_json(body)
+ return PreparedMessagesRequest(body=body, betas=tuple(dict.fromkeys(betas)))
diff --git a/src/free_claude_code/core/anthropic/native_stream.py b/src/free_claude_code/core/anthropic/native_stream.py
new file mode 100644
index 00000000..4c97220a
--- /dev/null
+++ b/src/free_claude_code/core/anthropic/native_stream.py
@@ -0,0 +1,254 @@
+"""Native Messages event validation and identity-preserving relay."""
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import cast
+
+from free_claude_code.core.json_types import JsonObject, JsonValue
+
+from .native import NativeMessagesError
+
+_STOP_REASONS = {
+ "end_turn",
+ "stop_sequence",
+ "tool_use",
+ "max_tokens",
+ "refusal",
+ "pause_turn",
+ "model_context_window_exceeded",
+}
+
+
+@dataclass(slots=True)
+class _Block:
+ body: JsonObject
+ parts: list[str] = field(default_factory=list)
+ fragments: dict[str, list[str]] = field(default_factory=dict)
+
+
+class NativeMessagesStreamState:
+ """Validate one upstream lifecycle without rewriting protocol identities."""
+
+ def __init__(self) -> None:
+ self.started = False
+ self.completed = False
+ self.stop_reason: str | None = None
+ self._blocks: dict[int, _Block] = {}
+ self._seen: set[int] = set()
+ self._tool_ids: set[str] = set()
+
+ def accept(
+ self, event_type: str, payload: Mapping[str, JsonValue]
+ ) -> JsonObject | None:
+ if self.completed:
+ raise NativeMessagesError("Messages event arrived after message_stop.")
+ try:
+ json.dumps(dict(payload), ensure_ascii=False, allow_nan=False).encode(
+ "utf-8"
+ )
+ except (ValueError, UnicodeError, RecursionError) as exc:
+ raise NativeMessagesError(
+ "Native Messages event is not representable JSON."
+ ) from exc
+ if payload.get("type") != event_type:
+ raise NativeMessagesError("Messages event type disagrees with its payload.")
+ if event_type == "ping":
+ return None
+ if event_type == "message_start":
+ if self.started:
+ raise NativeMessagesError("Duplicate message_start.")
+ message = payload.get("message")
+ if (
+ not isinstance(message, Mapping)
+ or not isinstance(message.get("id"), str)
+ or not message["id"]
+ or message.get("role") != "assistant"
+ or message.get("content", []) != []
+ ):
+ raise NativeMessagesError("Invalid native message_start.")
+ self.started = True
+ return None
+ if not self.started:
+ raise NativeMessagesError("Messages event arrived before message_start.")
+ if event_type == "message_delta":
+ delta = payload.get("delta")
+ if not isinstance(delta, Mapping):
+ raise NativeMessagesError("Native message_delta requires an object.")
+ reason = delta.get("stop_reason")
+ if reason is not None:
+ if self._blocks:
+ raise NativeMessagesError(
+ "Stop reason arrived with open content blocks."
+ )
+ if not isinstance(reason, str) or reason not in _STOP_REASONS:
+ raise NativeMessagesError(
+ "Unsupported native Messages stop reason."
+ )
+ if self.stop_reason is not None:
+ raise NativeMessagesError("Duplicate native Messages stop reason.")
+ self.stop_reason = reason
+ return None
+ if event_type == "message_stop":
+ if self._blocks or self.stop_reason is None:
+ raise NativeMessagesError(
+ "message_stop arrived before content or stop reason completed."
+ )
+ self.completed = True
+ return None
+ if event_type not in {
+ "content_block_start",
+ "content_block_delta",
+ "content_block_stop",
+ }:
+ raise NativeMessagesError(
+ f"Unsupported native Messages event: {event_type!r}."
+ )
+ if self.stop_reason is not None:
+ raise NativeMessagesError("Content arrived after the message stop reason.")
+ index = payload.get("index")
+ if not isinstance(index, int) or isinstance(index, bool) or index < 0:
+ raise NativeMessagesError(
+ "Messages block index must be a nonnegative integer."
+ )
+ if event_type == "content_block_start":
+ if index in self._seen:
+ raise NativeMessagesError("Duplicate Messages content block index.")
+ body = payload.get("content_block")
+ if not isinstance(body, Mapping) or not isinstance(body.get("type"), str):
+ raise NativeMessagesError("Invalid native content block.")
+ kind = body["type"]
+ if kind == "text" and not isinstance(body.get("text"), str):
+ raise NativeMessagesError("Native text block requires text.")
+ if kind == "thinking" and not isinstance(body.get("thinking"), str):
+ raise NativeMessagesError(
+ "Native thinking block requires thinking text."
+ )
+ if (
+ kind == "thinking"
+ and "signature" in body
+ and not isinstance(body["signature"], str)
+ ):
+ raise NativeMessagesError("Native thinking signature must be a string.")
+ if kind == "redacted_thinking" and (
+ not isinstance(body.get("data"), str) or not body["data"]
+ ):
+ raise NativeMessagesError("Redacted native thinking requires its data.")
+ if kind == "tool_use":
+ tool_id = body.get("id")
+ if (
+ not isinstance(tool_id, str)
+ or not tool_id
+ or tool_id in self._tool_ids
+ or not isinstance(body.get("name"), str)
+ or not body["name"]
+ or not isinstance(body.get("input"), Mapping)
+ ):
+ raise NativeMessagesError(
+ "Invalid or duplicate native tool identity/input."
+ )
+ self._tool_ids.add(tool_id)
+ self._blocks[index] = _Block(dict(body))
+ self._seen.add(index)
+ return None
+ block = self._blocks.get(index)
+ if block is None:
+ raise NativeMessagesError(
+ "Messages content event refers to a closed or unknown block."
+ )
+ if event_type == "content_block_delta":
+ delta = payload.get("delta")
+ if not isinstance(delta, Mapping):
+ raise NativeMessagesError("Native content delta must be an object.")
+ kind = delta.get("type")
+ target = (
+ {
+ "text_delta": ("text", "text"),
+ "thinking_delta": ("thinking", "thinking"),
+ "signature_delta": ("thinking", "signature"),
+ "input_json_delta": ("tool_use", "partial_json"),
+ }.get(kind)
+ if isinstance(kind, str)
+ else None
+ )
+ if target is None:
+ if kind == "citations_delta" and block.body["type"] == "text":
+ citation = delta.get("citation")
+ citations = block.body.get("citations")
+ if citations is None:
+ citations = []
+ if not isinstance(citation, Mapping) or not isinstance(
+ citations, list
+ ):
+ raise NativeMessagesError("Invalid native citation delta.")
+ block.body["citations"] = [*citations, dict(citation)]
+ return None
+ raise NativeMessagesError("Unsupported native content delta.")
+ block_type, key = target
+ value = delta.get(key)
+ if block.body["type"] != block_type or not isinstance(value, str):
+ raise NativeMessagesError(
+ "Native content delta does not match its block."
+ )
+ if key == "partial_json":
+ if block.body.get("input"):
+ raise NativeMessagesError(
+ "Tool input mixes eager content and JSON deltas."
+ )
+ block.parts.append(value)
+ else:
+ existing = block.body.get(key, "")
+ if not isinstance(existing, str):
+ raise NativeMessagesError("Native content field must be a string.")
+ block.fragments.setdefault(key, []).append(value)
+ return None
+ for key, parts in block.fragments.items():
+ initial = block.body.get(key, "")
+ if not isinstance(initial, str):
+ raise AssertionError("Validated native content fields must be strings.")
+ block.body[key] = initial + "".join(parts)
+ if block.body["type"] == "thinking" and not block.body.get("signature"):
+ raise NativeMessagesError(
+ "Completed native thinking requires its signature."
+ )
+ if block.body["type"] == "tool_use" and block.parts:
+ try:
+ value = cast(JsonValue, json.loads("".join(block.parts)))
+ if not isinstance(value, Mapping):
+ raise NativeMessagesError(
+ "Native tool arguments must decode to an object."
+ )
+ json.dumps(value, ensure_ascii=False, allow_nan=False).encode("utf-8")
+ except (ValueError, UnicodeError, RecursionError) as exc:
+ raise NativeMessagesError(
+ "Native tool arguments are incomplete or invalid JSON."
+ ) from exc
+ block.body["input"] = dict(value)
+ self._blocks.pop(index)
+ return block.body
+
+
+class NativeMessagesRelay:
+ """Preserve upstream IDs, indexes, fields and event order for Messages clients."""
+
+ def __init__(self, *, public_model: str) -> None:
+ self._public_model = public_model
+ self._state = NativeMessagesStreamState()
+
+ @property
+ def completed(self) -> bool:
+ return self._state.completed
+
+ @property
+ def stop_reason(self) -> str | None:
+ return self._state.stop_reason
+
+ def feed(self, event_type: str, payload: Mapping[str, JsonValue]) -> str:
+ self._state.accept(event_type, payload)
+ body = dict(payload)
+ if event_type == "message_start":
+ message = body.get("message")
+ if not isinstance(message, dict):
+ raise AssertionError("Validated message_start must contain a message.")
+ body["message"] = {**message, "model": self._public_model}
+ return f"event: {event_type}\ndata: {json.dumps(body, ensure_ascii=False)}\n\n"
diff --git a/src/free_claude_code/core/anthropic/sse_aggregation.py b/src/free_claude_code/core/anthropic/sse_aggregation.py
index 896c7bea..58940a1f 100644
--- a/src/free_claude_code/core/anthropic/sse_aggregation.py
+++ b/src/free_claude_code/core/anthropic/sse_aggregation.py
@@ -63,7 +63,16 @@ async def aggregate_anthropic_sse_to_message(
elif dtype == "input_json_delta":
parts[idx].append(str(delta.get("partial_json", "")))
elif dtype == "signature_delta":
- blocks[idx]["signature"] = str(delta.get("signature", ""))
+ blocks[idx]["signature"] = str(blocks[idx].get("signature", "")) + str(
+ delta.get("signature", "")
+ )
+ elif dtype == "citations_delta":
+ citation = delta.get("citation")
+ citations = blocks[idx].get("citations")
+ if citations is None:
+ citations = []
+ if isinstance(citation, dict) and isinstance(citations, list):
+ blocks[idx]["citations"] = [*citations, dict(citation)]
elif ptype == "message_delta":
delta = payload.get("delta")
if isinstance(delta, dict):
diff --git a/src/free_claude_code/core/anthropic/stream_contracts.py b/src/free_claude_code/core/anthropic/stream_contracts.py
index d635f4e0..49422ba3 100644
--- a/src/free_claude_code/core/anthropic/stream_contracts.py
+++ b/src/free_claude_code/core/anthropic/stream_contracts.py
@@ -4,6 +4,7 @@ Used by default CI contract tests and by opt-in live smoke scenarios.
"""
import json
+import re
from collections.abc import Iterable
from dataclasses import dataclass
from typing import Any
@@ -71,7 +72,8 @@ def parse_sse_lines(lines: Iterable[str]) -> list[SSEEvent]:
def parse_sse_text(text: str) -> list[SSEEvent]:
- return parse_sse_lines(text.splitlines())
+ # SSE uses CR/LF framing; Unicode line separators can occur inside JSON text.
+ return parse_sse_lines(re.split(r"\r\n|\r|\n", text))
def _append_event(
diff --git a/src/free_claude_code/core/anthropic/streaming/decoder.py b/src/free_claude_code/core/anthropic/streaming/decoder.py
index 33027f2a..6c7f66a3 100644
--- a/src/free_claude_code/core/anthropic/streaming/decoder.py
+++ b/src/free_claude_code/core/anthropic/streaming/decoder.py
@@ -4,7 +4,7 @@ import re
from ..stream_contracts import SSEEvent, parse_sse_text
-_EVENT_BOUNDARY = re.compile(r"\r?\n\r?\n")
+_EVENT_BOUNDARY = re.compile(r"(?>\r\n|\r|\n){2}")
class AnthropicSSEDecoder:
diff --git a/src/free_claude_code/core/openai_responses/__init__.py b/src/free_claude_code/core/openai_responses/__init__.py
index ac1ea8e6..81c4a32e 100644
--- a/src/free_claude_code/core/openai_responses/__init__.py
+++ b/src/free_claude_code/core/openai_responses/__init__.py
@@ -15,6 +15,8 @@ from .ids import (
new_reasoning_item_id,
new_response_id,
)
+from .messages_request import ResponsesMessagesRequest, build_responses_messages_request
+from .messages_stream import AnthropicToResponsesStream
from .models import OpenAIResponsesRequest
from .native import NativeResponsesRelay, build_native_responses_request
from .provider_input import build_responses_provider_request
@@ -24,6 +26,7 @@ from .provider_stream import (
responses_stream_failure_from_event,
)
from .reasoning import responses_reasoning_config, responses_reasoning_policy
+from .reasoning_replay import MessagesReplayOrigin
from .streaming.blocks import ReasoningBlockState, TextBlockState, ToolBlockState
from .streaming.completion import (
ResponseBlockCompleter,
@@ -34,10 +37,12 @@ from .streaming.error_mapping import replay_unsafe_function_call_error
from .streaming.event_builders import ResponseEventBuilder
from .streaming.ledger import ResponsesOutputLedger
from .tokens import estimate_responses_input_tokens
-from .tools import responses_tool_identity_from_anthropic_name
+from .tools import ResponsesToolIdentity, responses_tool_identity_from_anthropic_name
__all__ = [
"OPENAI_RESPONSES_SSE_HEADERS",
+ "AnthropicToResponsesStream",
+ "MessagesReplayOrigin",
"NativeResponsesRelay",
"OpenAIResponsesRequest",
"ReasoningBlockState",
@@ -45,13 +50,16 @@ __all__ = [
"ResponseEventBuilder",
"ResponsesChatRequest",
"ResponsesConversionError",
+ "ResponsesMessagesRequest",
"ResponsesOutputLedger",
"ResponsesProviderStream",
"ResponsesStreamFailure",
+ "ResponsesToolIdentity",
"TextBlockState",
"ToolBlockState",
"build_native_responses_request",
"build_responses_chat_request",
+ "build_responses_messages_request",
"build_responses_provider_request",
"committed_response_failure_frame",
"estimate_responses_input_tokens",
diff --git a/src/free_claude_code/core/openai_responses/chat_request.py b/src/free_claude_code/core/openai_responses/chat_request.py
index ce6709d0..32986cdb 100644
--- a/src/free_claude_code/core/openai_responses/chat_request.py
+++ b/src/free_claude_code/core/openai_responses/chat_request.py
@@ -23,6 +23,7 @@ from .reasoning import (
encrypted_reasoning_from_item,
reasoning_text_from_item,
)
+from .reasoning_replay import reject_messages_reasoning_for_other_egress
from .tools import (
call_id_from_item,
custom_tool_input_text,
@@ -309,6 +310,7 @@ def build_responses_chat_request(
structured_reasoning_details: bool = False,
) -> ResponsesChatRequest:
"""Translate a Responses request directly into one Chat Completions body."""
+ reject_messages_reasoning_for_other_egress(request.input)
builder = _ResponsesChatInputBuilder(
reasoning_replay=reasoning_replay,
structured_reasoning_details=structured_reasoning_details,
diff --git a/src/free_claude_code/core/openai_responses/messages_request.py b/src/free_claude_code/core/openai_responses/messages_request.py
new file mode 100644
index 00000000..1aa7eaaf
--- /dev/null
+++ b/src/free_claude_code/core/openai_responses/messages_request.py
@@ -0,0 +1,623 @@
+"""Direct Responses-to-Messages conversion with explicit replay and tool identity."""
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Literal, cast
+from urllib.parse import urlsplit
+
+from free_claude_code.core.anthropic.image_sources import (
+ AnthropicImageSourceError,
+ portable_anthropic_image_url,
+)
+from free_claude_code.core.anthropic.native import (
+ NativeMessagesError,
+ NativeMessagesOptions,
+ apply_messages_options,
+ validate_messages_json,
+)
+from free_claude_code.core.json_types import JsonObject, JsonValue
+from free_claude_code.core.openai_tool_names import OpenAIToolNameCodec
+
+from .errors import ResponsesConversionError
+from .models import OpenAIResponsesRequest
+from .reasoning_replay import decode_messages_reasoning
+from .tools import ResponsesToolIdentity, responses_tool_name_to_anthropic_name
+
+_REQUEST_FIELDS = {
+ "model",
+ "input",
+ "instructions",
+ "tools",
+ "tool_choice",
+ "parallel_tool_calls",
+ "stream",
+ "temperature",
+ "top_p",
+ "max_output_tokens",
+ "metadata",
+ "reasoning",
+ "previous_response_id",
+ "store",
+ "text",
+ "include",
+ "truncation",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ResponsesMessagesRequest:
+ body: JsonObject
+ tool_identities: Mapping[str, ResponsesToolIdentity]
+
+
+def _fields(value: Mapping[str, JsonValue], allowed: set[str], context: str) -> None:
+ unsupported = sorted(
+ key for key, item in value.items() if key not in allowed and item is not None
+ )
+ if unsupported:
+ raise ResponsesConversionError(
+ f"{context} cannot represent field(s): {', '.join(unsupported)}."
+ )
+
+
+def _string(value: JsonValue, context: str, *, empty: bool = False) -> str:
+ if not isinstance(value, str) or (not empty and not value.strip()):
+ raise ResponsesConversionError(
+ f"{context} must be a {'string' if empty else 'nonempty string'}."
+ )
+ return value
+
+
+def _items(value: JsonValue) -> list[JsonValue]:
+ if isinstance(value, str | Mapping):
+ return [value]
+ if isinstance(value, list):
+ return value
+ raise ResponsesConversionError(
+ "Messages upstream requires explicit Responses input history."
+ )
+
+
+def _identity(
+ value: Mapping[str, JsonValue],
+ kind: Literal["function", "custom"],
+ namespace: str | None = None,
+) -> ResponsesToolIdentity:
+ own_namespace = value.get("namespace")
+ if own_namespace is not None:
+ own_namespace = _string(own_namespace, "tool.namespace")
+ if namespace is not None and namespace != own_namespace:
+ raise ResponsesConversionError(
+ "Tool namespace conflicts with its declaration."
+ )
+ namespace = own_namespace
+ return ResponsesToolIdentity(
+ kind=kind, name=_string(value.get("name"), "tool.name"), namespace=namespace
+ )
+
+
+def _arguments(value: JsonValue) -> JsonObject:
+ if isinstance(value, Mapping):
+ return dict(value)
+ if not isinstance(value, str):
+ raise ResponsesConversionError("Function arguments must be a JSON object.")
+ try:
+ parsed = cast(JsonValue, json.loads(value))
+ except (ValueError, RecursionError) as exc:
+ raise ResponsesConversionError(
+ "Function arguments must be valid JSON."
+ ) from exc
+ if not isinstance(parsed, Mapping):
+ raise ResponsesConversionError("Function arguments must decode to an object.")
+ return dict(parsed)
+
+
+class _ToolScope:
+ def __init__(self, tools: list[JsonObject] | None, items: list[JsonValue]) -> None:
+ self._flat: dict[str, ResponsesToolIdentity] = {}
+ self._declared: set[ResponsesToolIdentity] = set()
+ definitions: list[tuple[ResponsesToolIdentity, JsonObject]] = []
+ for tool in tools or ():
+ if tool.get("type") == "namespace":
+ _fields(tool, {"type", "name", "description", "tools"}, "Namespace")
+ namespace = _string(tool.get("name"), "namespace.name")
+ nested = tool.get("tools")
+ if not isinstance(nested, list):
+ raise ResponsesConversionError("Namespace tools must be a list.")
+ description = tool.get("description")
+ if description is not None:
+ description = _string(
+ description, "namespace.description", empty=True
+ )
+ for child in nested:
+ if not isinstance(child, Mapping):
+ raise ResponsesConversionError(
+ "Namespace tool must be an object."
+ )
+ identity, body = self._definition(child, namespace)
+ if description:
+ own = body.get("description", "")
+ body["description"] = (
+ f"Namespace {namespace}: {description}\n\n{own}".rstrip()
+ )
+ definitions.append((identity, body))
+ else:
+ definitions.append(self._definition(tool, None))
+ for item in items:
+ if isinstance(item, Mapping) and item.get("type") in (
+ "function_call",
+ "custom_tool_call",
+ ):
+ kind = (
+ "custom" if item.get("type") == "custom_tool_call" else "function"
+ )
+ self._register(_identity(item, kind))
+ self._codec = OpenAIToolNameCodec.from_names(self._flat)
+ self.identities = MappingProxyType(
+ {
+ self._codec.encode(name): identity
+ for name, identity in self._flat.items()
+ }
+ )
+ self.tools: list[JsonValue] = []
+ for identity, body in definitions:
+ body["name"] = self.alias(identity)
+ self.tools.append(body)
+
+ def _register(self, identity: ResponsesToolIdentity) -> None:
+ name = responses_tool_name_to_anthropic_name(
+ identity.name, namespace=identity.namespace
+ )
+ previous = self._flat.get(name)
+ if previous is not None and previous != identity:
+ raise ResponsesConversionError(
+ "Tool identities collide after namespace flattening."
+ )
+ self._flat[name] = identity
+
+ def _definition(
+ self, value: Mapping[str, JsonValue], namespace: str | None
+ ) -> tuple[ResponsesToolIdentity, JsonObject]:
+ kind_value = value.get("type")
+ if kind_value not in ("function", "custom"):
+ raise ResponsesConversionError(
+ f"Messages upstream cannot represent tool type {kind_value!r}."
+ )
+ kind: Literal["function", "custom"] = (
+ "custom" if kind_value == "custom" else "function"
+ )
+ allowed = {"type", "name", "namespace", "description"}
+ allowed |= {"format"} if kind == "custom" else {"parameters", "strict"}
+ _fields(value, allowed, "Tool declaration")
+ identity = _identity(value, kind, namespace)
+ if identity in self._declared:
+ raise ResponsesConversionError("Duplicate tool declaration.")
+ self._declared.add(identity)
+ self._register(identity)
+ body: JsonObject = {}
+ if value.get("description") is not None:
+ body["description"] = _string(
+ value["description"], "tool.description", empty=True
+ )
+ if kind == "custom":
+ format_value = value.get("format")
+ if format_value is not None:
+ if (
+ not isinstance(format_value, Mapping)
+ or format_value.get("type") != "text"
+ ):
+ raise ResponsesConversionError(
+ "Messages upstream cannot enforce custom tool grammars."
+ )
+ _fields(format_value, {"type"}, "Custom tool format")
+ body["input_schema"] = {
+ "type": "object",
+ "properties": {"input": {"type": "string"}},
+ "required": ["input"],
+ "additionalProperties": False,
+ }
+ else:
+ schema = value.get("parameters", {"type": "object", "properties": {}})
+ if not isinstance(schema, Mapping):
+ raise ResponsesConversionError(
+ "Function parameters must be a schema object."
+ )
+ body["input_schema"] = dict(schema)
+ if value.get("strict") is not None:
+ strict = value["strict"]
+ if not isinstance(strict, bool):
+ raise ResponsesConversionError("Tool strict must be a boolean.")
+ body["strict"] = strict
+ return identity, body
+
+ def alias(self, identity: ResponsesToolIdentity) -> str:
+ name = responses_tool_name_to_anthropic_name(
+ identity.name, namespace=identity.namespace
+ )
+ if self._flat.get(name) != identity:
+ raise ResponsesConversionError("Unknown tool identity.")
+ return self._codec.encode(name)
+
+ def choice(self, value: JsonValue, parallel: bool | None) -> JsonObject | None:
+ choice: JsonObject | None = None
+ if value is not None:
+ if isinstance(value, str) and value in {"auto", "none", "required"}:
+ choice = {"type": "any" if value == "required" else value}
+ elif isinstance(value, Mapping):
+ kind = value.get("type")
+ if kind not in ("function", "custom"):
+ raise ResponsesConversionError("Unsupported named tool choice.")
+ _fields(value, {"type", "name", "namespace"}, "Tool choice")
+ identity = _identity(
+ value, "custom" if kind == "custom" else "function"
+ )
+ if identity not in self._declared:
+ raise ResponsesConversionError(
+ "Named tool choice must refer to a declared tool."
+ )
+ choice = {"type": "tool", "name": self.alias(identity)}
+ else:
+ raise ResponsesConversionError("Unsupported Responses tool choice.")
+ if choice is not None and choice["type"] in {"any", "tool"} and not self.tools:
+ raise ResponsesConversionError(
+ "Forced tool choice requires declared tools."
+ )
+ if (
+ parallel is False
+ and self.tools
+ and (choice is None or choice["type"] != "none")
+ ):
+ choice = choice or {"type": "auto"}
+ choice["disable_parallel_tool_use"] = True
+ return choice
+
+
+def _image(value: Mapping[str, JsonValue]) -> JsonObject:
+ _fields(value, {"type", "image_url", "detail", "file_id"}, "Image")
+ if value.get("file_id") is not None:
+ raise ResponsesConversionError(
+ "A Messages upstream requires image content or a portable URL, not file_id."
+ )
+ if value.get("detail") not in (None, "auto"):
+ raise ResponsesConversionError(
+ "Messages upstream cannot represent the requested image detail control."
+ )
+ url = _string(value.get("image_url"), "input_image.image_url")
+ if url.lower().startswith("data:"):
+ prefix, separator, data = url.partition(";base64,")
+ if not separator:
+ raise ResponsesConversionError(
+ "Image data URL must contain base64 content."
+ )
+ source: JsonObject = {"type": "base64", "media_type": prefix[5:], "data": data}
+ try:
+ normalized = portable_anthropic_image_url(source)
+ except AnthropicImageSourceError as exc:
+ raise ResponsesConversionError(str(exc)) from exc
+ source["data"] = normalized.partition(";base64,")[2]
+ source["media_type"] = prefix[5:].lower()
+ else:
+ parsed = urlsplit(url)
+ if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+ raise ResponsesConversionError("Image URL must use HTTP or HTTPS.")
+ source = {"type": "url", "url": url}
+ return {"type": "image", "source": source}
+
+
+def _content(value: JsonValue, *, images: bool, empty: bool = False) -> list[JsonValue]:
+ if isinstance(value, str):
+ text = _string(value, "content", empty=empty)
+ return [{"type": "text", "text": text}] if text else []
+ if not isinstance(value, list):
+ raise ResponsesConversionError(
+ "Message content must be text or a list of supported blocks."
+ )
+ blocks: list[JsonValue] = []
+ for item in value:
+ if not isinstance(item, Mapping):
+ raise ResponsesConversionError("Message content blocks must be objects.")
+ kind = item.get("type")
+ if kind in ("input_text", "output_text", "text"):
+ _fields(item, {"type", "text", "annotations", "logprobs"}, "Text block")
+ if item.get("annotations") or item.get("logprobs"):
+ raise ResponsesConversionError(
+ "Messages history cannot represent text annotations or logprobs."
+ )
+ text = _string(item.get("text"), "content.text", empty=empty)
+ if text:
+ blocks.append({"type": "text", "text": text})
+ elif kind == "input_image" and images:
+ blocks.append(_image(item))
+ else:
+ raise ResponsesConversionError(
+ f"Messages upstream cannot represent content type {kind!r}."
+ )
+ return blocks
+
+
+class _MessagesInput:
+ def __init__(self, tools: _ToolScope, replay_scope: str) -> None:
+ self.messages: list[JsonObject] = []
+ self.system: list[JsonValue] = []
+ self._tools = tools
+ self._replay_scope = replay_scope
+ self._calls: dict[str, Literal["function", "custom"]] = {}
+ self._pending: set[str] = set()
+
+ def _append(
+ self,
+ role: Literal["user", "assistant"],
+ parts: list[JsonValue],
+ *,
+ result: bool = False,
+ ) -> None:
+ if (
+ self._pending
+ and not result
+ and (
+ role == "user"
+ or not self.messages
+ or self.messages[-1]["role"] != "assistant"
+ )
+ ):
+ raise ResponsesConversionError(
+ "Tool results must immediately follow their assistant call group."
+ )
+ if self.messages and self.messages[-1]["role"] == role:
+ content = self.messages[-1]["content"]
+ if not isinstance(content, list):
+ raise AssertionError("Native content must be a list.")
+ content.extend(parts)
+ else:
+ self.messages.append({"role": role, "content": parts})
+
+ def add(self, value: JsonValue) -> None:
+ if isinstance(value, str):
+ self._append("user", [{"type": "text", "text": value}])
+ return
+ if not isinstance(value, Mapping):
+ raise ResponsesConversionError(
+ "Responses input items must be text or objects."
+ )
+ kind = value.get("type")
+ if kind is None or kind == "message":
+ _fields(value, {"type", "role", "content", "id", "status"}, "Message")
+ role = value.get("role", "user")
+ if role in ("system", "developer"):
+ if self.messages:
+ raise ResponsesConversionError(
+ "Messages upstream supports only leading system/developer input."
+ )
+ self.system.extend(_content(value.get("content"), images=False))
+ elif role in ("user", "assistant"):
+ self._append(
+ "user" if role == "user" else "assistant",
+ _content(value.get("content"), images=role == "user"),
+ )
+ else:
+ raise ResponsesConversionError("Unsupported Responses message role.")
+ return
+ if kind == "reasoning":
+ _fields(
+ value,
+ {"type", "id", "status", "summary", "content", "encrypted_content"},
+ "Reasoning item",
+ )
+ carrier = _string(
+ value.get("encrypted_content"), "reasoning.encrypted_content"
+ )
+ block = decode_messages_reasoning(carrier, replay_scope=self._replay_scope)
+ self._append("assistant", [block])
+ return
+ if kind in ("function_call", "custom_tool_call"):
+ self._call(value, custom=kind == "custom_tool_call")
+ return
+ if kind in ("function_call_output", "custom_tool_call_output"):
+ self._result(value, custom=kind == "custom_tool_call_output")
+ return
+ if kind in ("input_text", "output_text", "text", "input_image"):
+ self._append("user", _content([value], images=True))
+ return
+ raise ResponsesConversionError(
+ f"Messages upstream cannot represent input item {kind!r}."
+ )
+
+ def _call(self, value: Mapping[str, JsonValue], *, custom: bool) -> None:
+ _fields(
+ value,
+ {
+ "type",
+ "id",
+ "status",
+ "call_id",
+ "name",
+ "namespace",
+ "input" if custom else "arguments",
+ },
+ "Tool call",
+ )
+ call_id = _string(value.get("call_id"), "tool.call_id")
+ if call_id in self._calls:
+ raise ResponsesConversionError(
+ "Duplicate tool call_id in Responses history."
+ )
+ kind = "custom" if custom else "function"
+ identity = _identity(value, kind)
+ arguments: JsonObject = (
+ {"input": _string(value.get("input"), "custom_tool_call.input", empty=True)}
+ if custom
+ else _arguments(value.get("arguments"))
+ )
+ self._append(
+ "assistant",
+ [
+ {
+ "type": "tool_use",
+ "id": call_id,
+ "name": self._tools.alias(identity),
+ "input": arguments,
+ }
+ ],
+ )
+ self._calls[call_id] = kind
+ self._pending.add(call_id)
+
+ def _result(self, value: Mapping[str, JsonValue], *, custom: bool) -> None:
+ _fields(
+ value,
+ {"type", "id", "status", "call_id", "output", "is_error"},
+ "Tool output",
+ )
+ call_id = _string(value.get("call_id"), "tool output.call_id")
+ if call_id not in self._pending:
+ raise ResponsesConversionError("Tool output is orphaned or duplicated.")
+ if self._calls[call_id] != ("custom" if custom else "function"):
+ raise ResponsesConversionError("Tool output type does not match its call.")
+ block: JsonObject = {
+ "type": "tool_result",
+ "tool_use_id": call_id,
+ }
+ content = _content(value.get("output"), images=True, empty=True)
+ if content:
+ block["content"] = content
+ if value.get("is_error") is not None:
+ if not isinstance(value["is_error"], bool):
+ raise ResponsesConversionError(
+ "Tool result is_error must be a boolean."
+ )
+ block["is_error"] = value["is_error"]
+ self._append("user", [block], result=True)
+ self._pending.remove(call_id)
+
+ def finish(self) -> None:
+ if self._pending:
+ raise ResponsesConversionError(
+ "Responses history has unresolved tool calls."
+ )
+ if not self.messages:
+ raise ResponsesConversionError(
+ "Messages upstream requires conversational input."
+ )
+
+
+def _output_format(value: JsonValue) -> JsonObject | None:
+ if value is None:
+ return None
+ if not isinstance(value, Mapping):
+ raise ResponsesConversionError("Responses text options must be an object.")
+ _fields(value, {"format"}, "Text options")
+ format_value = value.get("format")
+ if format_value is None:
+ return None
+ if not isinstance(format_value, Mapping):
+ raise ResponsesConversionError("Responses text.format must be an object.")
+ kind = format_value.get("type")
+ if kind == "text":
+ _fields(format_value, {"type"}, "Text format")
+ return None
+ if kind != "json_schema":
+ raise ResponsesConversionError(
+ "Messages upstream supports text or json_schema output."
+ )
+ _fields(
+ format_value,
+ {"type", "name", "description", "schema", "strict"},
+ "Output format",
+ )
+ schema = format_value.get("schema")
+ if not isinstance(schema, Mapping):
+ raise ResponsesConversionError("Output format schema must be an object.")
+ strict = format_value.get("strict")
+ if strict is not None and not isinstance(strict, bool):
+ raise ResponsesConversionError("Output format strict must be a boolean.")
+ if strict is False:
+ raise ResponsesConversionError(
+ "Messages structured output always enforces its schema."
+ )
+ converted = dict(schema)
+ # Carry descriptive schema metadata into its native JSON Schema locations.
+ if format_value.get("name") is not None:
+ name = _string(format_value["name"], "output format.name")
+ if "title" in converted and converted["title"] != name:
+ raise ResponsesConversionError(
+ "Output format name conflicts with schema title."
+ )
+ converted["title"] = name
+ if format_value.get("description") is not None:
+ description = _string(
+ format_value["description"], "output format.description", empty=True
+ )
+ if "description" in converted and converted["description"] != description:
+ raise ResponsesConversionError(
+ "Output description conflicts with its schema."
+ )
+ converted["description"] = description
+ return {"type": "json_schema", "schema": converted}
+
+
+def build_responses_messages_request(
+ request: OpenAIResponsesRequest,
+ *,
+ options: NativeMessagesOptions,
+ replay_scope: str,
+) -> ResponsesMessagesRequest:
+ """Convert caller-owned history directly to the native Messages wire shape."""
+
+ raw = cast(JsonObject, request.model_dump(mode="json", exclude_none=True))
+ _fields(raw, _REQUEST_FIELDS, "Responses request")
+ if raw.get("truncation") not in (None, "disabled"):
+ raise ResponsesConversionError(
+ "Messages upstream does not support automatic input truncation."
+ )
+ include = raw.get("include")
+ if include is not None and (
+ not isinstance(include, list)
+ or any(item != "reasoning.encrypted_content" for item in include)
+ ):
+ raise ResponsesConversionError(
+ "Messages upstream cannot represent the requested include fields."
+ )
+ if request.reasoning is not None:
+ _fields(request.reasoning, {"effort", "summary"}, "Reasoning controls")
+ if request.reasoning.get("summary") not in (None, "auto"):
+ raise ResponsesConversionError(
+ "Messages upstream supports only automatic reasoning summaries."
+ )
+ items = _items(request.input)
+ scope = _ToolScope(request.tools, items)
+ builder = _MessagesInput(scope, replay_scope)
+ if request.instructions is not None:
+ builder.system.append({"type": "text", "text": request.instructions})
+ for item in items:
+ builder.add(item)
+ builder.finish()
+ body: JsonObject = {"messages": builder.messages}
+ if builder.system:
+ body["system"] = builder.system
+ if scope.tools:
+ body["tools"] = scope.tools
+ choice = scope.choice(request.tool_choice, request.parallel_tool_calls)
+ if choice is not None:
+ body["tool_choice"] = choice
+ for key in ("temperature", "top_p"):
+ if key in raw:
+ body[key] = raw[key]
+ if request.metadata is not None:
+ _fields(request.metadata, {"user_id"}, "Metadata")
+ if "user_id" in request.metadata:
+ body["metadata"] = {
+ "user_id": _string(
+ request.metadata["user_id"], "metadata.user_id", empty=True
+ )
+ }
+ output_format = _output_format(raw.get("text"))
+ if output_format is not None:
+ body["output_config"] = {"format": output_format}
+ try:
+ apply_messages_options(body, options)
+ validate_messages_json(body)
+ except NativeMessagesError as exc:
+ raise ResponsesConversionError(str(exc)) from exc
+ return ResponsesMessagesRequest(body=body, tool_identities=scope.identities)
diff --git a/src/free_claude_code/core/openai_responses/messages_stream.py b/src/free_claude_code/core/openai_responses/messages_stream.py
new file mode 100644
index 00000000..2d937a71
--- /dev/null
+++ b/src/free_claude_code/core/openai_responses/messages_stream.py
@@ -0,0 +1,390 @@
+"""Present native Anthropic Messages events as one Responses lifecycle."""
+
+import json
+import time
+import uuid
+from collections.abc import Mapping
+from typing import cast
+
+from free_claude_code.core.anthropic.native import NativeMessagesError
+from free_claude_code.core.anthropic.native_stream import NativeMessagesStreamState
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.json_types import JsonObject, JsonValue
+
+from .errors import ResponsesConversionError, openai_error_from_failure
+from .ids import new_message_item_id, new_reasoning_item_id, new_response_id
+from .items import message_item, reasoning_item
+from .models import OpenAIResponsesRequest
+from .reasoning_replay import MessagesReplayOrigin, encode_messages_reasoning
+from .streaming.blocks import ReasoningBlockState, TextBlockState, ToolBlockState
+from .streaming.completion import ResponseBlockCompleter, tool_item
+from .streaming.event_builders import ResponseEventBuilder
+from .streaming.ledger import ResponsesOutputLedger
+from .tools import ResponsesToolIdentity
+
+
+class _NativeUsage:
+ def __init__(self) -> None:
+ self._counts: dict[str, int] = {}
+ self._cache_creation: JsonObject | None = None
+ self._thinking_tokens: int | None = None
+ self._final_output_seen = False
+
+ def update(self, value: JsonValue, *, final: bool = False) -> None:
+ if final:
+ self._thinking_tokens = None
+ output = value.get("output_tokens") if isinstance(value, Mapping) else None
+ self._final_output_seen = (
+ isinstance(output, int) and not isinstance(output, bool) and output >= 0
+ )
+ if not isinstance(value, Mapping):
+ return
+ for key in (
+ "input_tokens",
+ "cache_read_input_tokens",
+ "cache_creation_input_tokens",
+ "output_tokens",
+ ):
+ count = value.get(key)
+ if isinstance(count, int) and not isinstance(count, bool) and count >= 0:
+ self._counts[key] = count
+ creation = value.get("cache_creation")
+ if isinstance(creation, Mapping):
+ self._cache_creation = {
+ key: count
+ for key, count in creation.items()
+ if isinstance(count, int) and not isinstance(count, bool) and count >= 0
+ }
+ details = value.get("output_tokens_details")
+ if isinstance(details, Mapping):
+ thinking = details.get("thinking_tokens")
+ if (
+ isinstance(thinking, int)
+ and not isinstance(thinking, bool)
+ and thinking >= 0
+ ):
+ self._thinking_tokens = thinking
+
+ def payload(self, *, require_final: bool = False) -> JsonObject | None:
+ if require_final and not self._final_output_seen:
+ return None
+ if "input_tokens" not in self._counts or "output_tokens" not in self._counts:
+ return None
+ cached = self._counts.get("cache_read_input_tokens", 0)
+ created = self._counts.get("cache_creation_input_tokens", 0)
+ input_tokens = self._counts["input_tokens"] + cached + created
+ output_tokens = self._counts["output_tokens"]
+ details: JsonObject = {}
+ if "cache_read_input_tokens" in self._counts:
+ details["cached_tokens"] = cached
+ if "cache_creation_input_tokens" in self._counts:
+ details["cache_creation_tokens"] = created
+ if self._cache_creation is not None:
+ details["cache_creation"] = dict(self._cache_creation)
+ usage: JsonObject = {
+ "input_tokens": input_tokens,
+ "output_tokens": output_tokens,
+ "total_tokens": input_tokens + output_tokens,
+ }
+ if details:
+ usage["input_tokens_details"] = details
+ if self._thinking_tokens is not None and self._thinking_tokens <= output_tokens:
+ usage["output_tokens_details"] = {"reasoning_tokens": self._thinking_tokens}
+ return usage
+
+
+class AnthropicToResponsesStream:
+ """Keep native block order and signed replay without using a Chat presenter."""
+
+ def __init__(
+ self,
+ request: OpenAIResponsesRequest,
+ *,
+ public_model: str,
+ tool_identities: Mapping[str, ResponsesToolIdentity],
+ replay_origin: MessagesReplayOrigin,
+ ) -> None:
+ self._request = request
+ self._public_model = public_model
+ self._identities = tool_identities
+ self._replay_origin = replay_origin
+ self._response_id = new_response_id()
+ self._created_at = int(time.time())
+ self._native = NativeMessagesStreamState()
+ self._ledger = ResponsesOutputLedger()
+ self._events = ResponseEventBuilder()
+ self._usage = _NativeUsage()
+ self._terminal = False
+ self._started = False
+ self._completer = ResponseBlockCompleter(
+ self._ledger,
+ events=self._events,
+ on_invalid_function_call=self._invalid_function,
+ )
+
+ @property
+ def completed(self) -> bool:
+ return self._terminal
+
+ def start(self) -> list[str]:
+ return []
+
+ def _payload(
+ self, status: str, *, failure: ExecutionFailure | None = None
+ ) -> JsonObject:
+ payload: JsonObject = {
+ "id": self._response_id,
+ "object": "response",
+ "created_at": self._created_at,
+ "status": status,
+ "model": self._public_model,
+ "output": cast(JsonValue, self._ledger.output()),
+ "tools": self._request.tools or [],
+ "tool_choice": self._request.tool_choice or "auto",
+ "parallel_tool_calls": self._request.parallel_tool_calls
+ if self._request.parallel_tool_calls is not None
+ else True,
+ "usage": self._usage.payload(require_final=status != "in_progress"),
+ "error": cast(JsonValue, openai_error_from_failure(failure))
+ if failure is not None
+ else None,
+ "incomplete_details": {"reason": "max_output_tokens"}
+ if status == "incomplete"
+ else None,
+ }
+ for key, value in (
+ ("instructions", self._request.instructions),
+ ("max_output_tokens", self._request.max_output_tokens),
+ ("temperature", self._request.temperature),
+ ("top_p", self._request.top_p),
+ ("metadata", self._request.metadata),
+ ("reasoning", self._request.reasoning),
+ ):
+ if value is not None:
+ payload[key] = value
+ return payload
+
+ def feed(self, event_type: str, payload: Mapping[str, JsonValue]) -> list[str]:
+ if self._terminal:
+ raise NativeMessagesError(
+ "Native event arrived after the Responses terminal event."
+ )
+ completed = self._native.accept(event_type, payload)
+ if event_type == "ping":
+ return []
+ if event_type == "message_start":
+ message = payload["message"]
+ if not isinstance(message, Mapping):
+ raise AssertionError("Validated message_start must contain a message.")
+ self._usage.update(message.get("usage"))
+ self._started = True
+ return [self._events.response_created(self._payload("in_progress"))]
+ if event_type == "message_delta":
+ delta = payload.get("delta")
+ self._usage.update(
+ payload.get("usage"),
+ final=isinstance(delta, Mapping)
+ and delta.get("stop_reason") is not None,
+ )
+ return []
+ if event_type == "message_stop":
+ reason = self._native.stop_reason
+ if reason not in {
+ "end_turn",
+ "stop_sequence",
+ "tool_use",
+ "max_tokens",
+ "refusal",
+ }:
+ raise NativeMessagesError(
+ f"Responses cannot represent native stop reason {reason!r}."
+ )
+ self._terminal = True
+ if reason == "max_tokens":
+ return [self._events.response_incomplete(self._payload("incomplete"))]
+ return [self._events.response_completed(self._payload("completed"))]
+ index = payload["index"]
+ if not isinstance(index, int):
+ raise AssertionError("Validated native content event must have an index.")
+ if event_type == "content_block_start":
+ block = payload["content_block"]
+ if not isinstance(block, Mapping):
+ raise AssertionError("Validated content_block_start must have a block.")
+ return self._start_block(index, block)
+ if event_type == "content_block_delta":
+ delta = payload["delta"]
+ if not isinstance(delta, Mapping):
+ raise AssertionError("Validated content delta must be an object.")
+ return self._delta(index, delta)
+ if event_type == "content_block_stop":
+ if completed is None:
+ raise AssertionError("Validated content stop must return its block.")
+ return self._finish_block(index, completed)
+ raise NativeMessagesError(f"Unsupported native event {event_type!r}.")
+
+ def _start_block(self, index: int, block: Mapping[str, JsonValue]) -> list[str]:
+ slot = self._ledger.reserve_output_slot()
+ kind = block.get("type")
+ if kind == "text":
+ if any(
+ key not in {"type", "text", "citations"} for key in block
+ ) or block.get("citations"):
+ raise NativeMessagesError(
+ "Responses cannot represent native text extensions."
+ )
+ text = block["text"]
+ if not isinstance(text, str):
+ raise AssertionError("Validated native text must be a string.")
+ state = TextBlockState(index, slot, new_message_item_id())
+ self._ledger.set_active_block(state)
+ events = [
+ self._events.output_item_added(
+ slot, message_item(state.item_id, "", "in_progress")
+ ),
+ self._events.content_part_added(state.item_id, slot),
+ ]
+ if text:
+ state.text_parts.append(text)
+ events.append(self._events.output_text_delta(state.item_id, slot, text))
+ return events
+ if kind in {"thinking", "redacted_thinking"}:
+ state = ReasoningBlockState(index, slot, new_reasoning_item_id())
+ self._ledger.set_active_block(state)
+ text = block.get("thinking", "")
+ if not isinstance(text, str):
+ raise NativeMessagesError("Native thinking text must be a string.")
+ events = [
+ self._events.output_item_added(
+ slot, reasoning_item(state.item_id, "", "in_progress")
+ )
+ ]
+ if text:
+ state.text_parts.append(text)
+ events.append(
+ self._events.reasoning_text_delta(state.item_id, slot, text)
+ )
+ return events
+ if kind != "tool_use":
+ raise NativeMessagesError(
+ f"Responses cannot represent native block type {kind!r}."
+ )
+ if any(key not in {"type", "id", "name", "input", "caller"} for key in block):
+ raise NativeMessagesError(
+ "Responses cannot represent native tool extensions."
+ )
+ caller = block.get("caller")
+ if caller is not None and caller != {"type": "direct"}:
+ raise NativeMessagesError(
+ "Responses cannot represent a server-managed tool caller."
+ )
+ name = block["name"]
+ call_id = block["id"]
+ if not isinstance(name, str) or not isinstance(call_id, str):
+ raise AssertionError("Validated native tools must have string identities.")
+ identity = self._identities.get(name)
+ if identity is None:
+ raise NativeMessagesError("Native output used an unknown tool name.")
+ tool = ToolBlockState(
+ index,
+ slot,
+ f"fc_{uuid.uuid4().hex}",
+ call_id,
+ identity.kind,
+ identity.name,
+ namespace=identity.namespace,
+ )
+ self._ledger.set_active_block(tool)
+ return [
+ self._events.output_item_added(slot, tool_item(tool, status="in_progress"))
+ ]
+
+ def _delta(self, index: int, delta: Mapping[str, JsonValue]) -> list[str]:
+ state = self._ledger.active_block(index)
+ kind = delta.get("type")
+ if isinstance(state, TextBlockState) and kind == "text_delta":
+ text = delta["text"]
+ if not isinstance(text, str):
+ raise AssertionError("Validated text delta must be a string.")
+ state.text_parts.append(text)
+ return [
+ self._events.output_text_delta(state.item_id, state.output_index, text)
+ ]
+ if isinstance(state, ReasoningBlockState) and kind == "thinking_delta":
+ text = delta["thinking"]
+ if not isinstance(text, str):
+ raise AssertionError("Validated thinking delta must be a string.")
+ state.text_parts.append(text)
+ return [
+ self._events.reasoning_text_delta(
+ state.item_id, state.output_index, text
+ )
+ ]
+ if isinstance(state, ReasoningBlockState) and kind == "signature_delta":
+ return []
+ if isinstance(state, ToolBlockState) and kind == "input_json_delta":
+ # The completer emits validated arguments once, after native block stop.
+ return []
+ raise NativeMessagesError(
+ "Responses cannot represent the native content delta."
+ )
+
+ def _finish_block(self, index: int, block: JsonObject) -> list[str]:
+ state = self._ledger.active_block(index)
+ if state is None:
+ raise NativeMessagesError(
+ "Native block has no corresponding Responses item."
+ )
+ if isinstance(state, ReasoningBlockState):
+ state.encrypted_content = encode_messages_reasoning(
+ block, origin=self._replay_origin
+ )
+ elif isinstance(state, ToolBlockState):
+ arguments = block.get("input")
+ if not isinstance(arguments, Mapping):
+ raise NativeMessagesError("Native tool input must be an object.")
+ if state.kind == "custom" and (
+ set(arguments) != {"input"}
+ or not isinstance(arguments.get("input"), str)
+ ):
+ raise NativeMessagesError(
+ "Native custom tool input must contain exactly one text input."
+ )
+ state.argument_parts.append(
+ json.dumps(arguments, ensure_ascii=False, separators=(",", ":"))
+ )
+ events = self._completer.complete_block(state)
+ self._ledger.pop_active_block(index)
+ return events
+
+ @staticmethod
+ def _invalid_function(
+ _state: ToolBlockState, error: ResponsesConversionError
+ ) -> list[str]:
+ raise NativeMessagesError("Native tool arguments are invalid.") from error
+
+ def terminal_failure(self, failure: ExecutionFailure) -> list[str]:
+ """Terminate once without completing partial tools or inventing arguments."""
+
+ if self._terminal:
+ return []
+ events: list[str] = []
+ if not self._started:
+ self._started = True
+ events.append(self._events.response_created(self._payload("in_progress")))
+ for state in self._ledger.pop_active_blocks_by_output_order():
+ if isinstance(state, TextBlockState):
+ item = message_item(
+ state.item_id, "".join(state.text_parts), "incomplete"
+ )
+ elif isinstance(state, ReasoningBlockState):
+ item = reasoning_item(
+ state.item_id, "".join(state.text_parts), "incomplete"
+ )
+ else:
+ item = tool_item(state, status="incomplete")
+ self._ledger.commit_output(state.output_index, item)
+ self._terminal = True
+ events.append(
+ self._events.response_failed(self._payload("failed", failure=failure))
+ )
+ return events
diff --git a/src/free_claude_code/core/openai_responses/models.py b/src/free_claude_code/core/openai_responses/models.py
index 3bce877a..427881b4 100644
--- a/src/free_claude_code/core/openai_responses/models.py
+++ b/src/free_claude_code/core/openai_responses/models.py
@@ -1,6 +1,6 @@
"""Pydantic models for OpenAI Responses-compatible ingress."""
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, field_validator
from free_claude_code.core.json_types import JsonObject, JsonValue
@@ -24,3 +24,10 @@ class OpenAIResponsesRequest(BaseModel):
reasoning: JsonObject | None = None
previous_response_id: str | None = None
store: bool | None = None
+
+ @field_validator("max_output_tokens", mode="before")
+ @classmethod
+ def _reject_boolean_output_limit(cls, value: object) -> object:
+ if isinstance(value, bool):
+ raise ValueError("max_output_tokens must not be a boolean")
+ return value
diff --git a/src/free_claude_code/core/openai_responses/native.py b/src/free_claude_code/core/openai_responses/native.py
index 5cd95512..917c8bc0 100644
--- a/src/free_claude_code/core/openai_responses/native.py
+++ b/src/free_claude_code/core/openai_responses/native.py
@@ -13,6 +13,7 @@ from .errors import openai_error_from_failure
from .events import format_response_sse_event
from .models import OpenAIResponsesRequest
from .reasoning import responses_reasoning_config, responses_reasoning_policy
+from .reasoning_replay import reject_messages_reasoning_for_other_egress
_TERMINAL_EVENT_TYPES = frozenset(
{"response.completed", "response.incomplete", "response.failed"}
@@ -27,6 +28,7 @@ def build_native_responses_request(
) -> JsonObject:
"""Build the stateless upstream body without translating Responses input."""
+ reject_messages_reasoning_for_other_egress(request.input)
body = cast(
JsonObject,
request.model_dump(mode="json", exclude_none=True),
diff --git a/src/free_claude_code/core/openai_responses/reasoning_replay.py b/src/free_claude_code/core/openai_responses/reasoning_replay.py
new file mode 100644
index 00000000..5203cbf9
--- /dev/null
+++ b/src/free_claude_code/core/openai_responses/reasoning_replay.py
@@ -0,0 +1,155 @@
+"""Versioned native-thinking replay carried by Responses reasoning items."""
+
+import base64
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import cast
+
+from free_claude_code.core.json_types import JsonObject, JsonValue
+
+from .errors import ResponsesConversionError
+
+_REASONING_FAMILY = "fcc:anthropic-reasoning:"
+_REASONING_PREFIX = _REASONING_FAMILY + "v1:"
+_MAX_REPLAY_DEPTH = 128
+
+
+@dataclass(frozen=True, slots=True)
+class MessagesReplayOrigin:
+ replay_scope: str
+ source_model: str
+
+
+def is_messages_reasoning_carrier(value: object) -> bool:
+ return isinstance(value, str) and value.startswith(_REASONING_FAMILY)
+
+
+def _validate_block(block: JsonValue) -> JsonObject:
+ if not isinstance(block, Mapping):
+ raise ResponsesConversionError(
+ "Native reasoning replay block must be an object."
+ )
+ kind = block.get("type")
+ if kind == "thinking":
+ if not isinstance(block.get("thinking"), str):
+ raise ResponsesConversionError(
+ "Native thinking replay requires thinking text."
+ )
+ if not isinstance(block.get("signature"), str) or not block["signature"]:
+ raise ResponsesConversionError(
+ "Native thinking replay requires its signature."
+ )
+ elif kind == "redacted_thinking":
+ if not isinstance(block.get("data"), str) or not block["data"]:
+ raise ResponsesConversionError(
+ "Redacted native thinking requires its data."
+ )
+ else:
+ raise ResponsesConversionError("Unsupported native reasoning replay block.")
+ pending: list[tuple[JsonValue, int]] = [(block, 0)]
+ while pending:
+ value, depth = pending.pop()
+ if depth > _MAX_REPLAY_DEPTH:
+ raise ResponsesConversionError(
+ "Native reasoning replay is too deeply nested."
+ )
+ if isinstance(value, Mapping):
+ pending.extend((child, depth + 1) for child in value.values())
+ elif isinstance(value, Sequence) and not isinstance(value, str | bytes):
+ pending.extend((child, depth + 1) for child in value)
+ try:
+ # A carrier can hide malformed JSON inside an otherwise ordinary string.
+ # Validate finite numbers and nesting before HTTP serialization.
+ return cast(
+ JsonObject,
+ json.loads(
+ json.dumps(dict(block), ensure_ascii=False, allow_nan=False).encode(
+ "utf-8"
+ )
+ ),
+ )
+ except (TypeError, ValueError, RecursionError) as exc:
+ raise ResponsesConversionError(
+ "Native reasoning replay must contain finite, representable JSON."
+ ) from exc
+
+
+def encode_messages_reasoning(
+ block: JsonObject, *, origin: MessagesReplayOrigin
+) -> str:
+ """Serialize native signed data; this does not add encryption or authentication."""
+
+ if not origin.replay_scope or not origin.source_model:
+ raise ResponsesConversionError(
+ "Native reasoning replay requires provider provenance."
+ )
+ payload: JsonObject = {
+ "protocol": "anthropic_messages",
+ "replay_scope": origin.replay_scope,
+ "source_model": origin.source_model,
+ "block": _validate_block(block),
+ }
+ try:
+ encoded = json.dumps(
+ payload, ensure_ascii=False, separators=(",", ":"), allow_nan=False
+ ).encode("utf-8")
+ except (ValueError, UnicodeError, RecursionError) as exc:
+ raise ResponsesConversionError(
+ "Malformed native Messages reasoning replay."
+ ) from exc
+ return _REASONING_PREFIX + base64.urlsafe_b64encode(encoded).decode("ascii").rstrip(
+ "="
+ )
+
+
+def decode_messages_reasoning(value: str, *, replay_scope: str) -> JsonObject:
+ """Validate provenance and return the exact authoritative replay block."""
+
+ if not value.startswith(_REASONING_PREFIX):
+ raise ResponsesConversionError(
+ "This reasoning item is not a supported native Messages replay carrier."
+ )
+ encoded = value[len(_REASONING_PREFIX) :]
+ try:
+ raw = base64.b64decode(
+ encoded + "=" * (-len(encoded) % 4), altchars=b"-_", validate=True
+ )
+ payload = cast(JsonValue, json.loads(raw.decode("utf-8")))
+ except (ValueError, UnicodeError, RecursionError) as exc:
+ raise ResponsesConversionError(
+ "Malformed native Messages reasoning replay."
+ ) from exc
+ if (
+ not isinstance(payload, Mapping)
+ or set(payload) != {"protocol", "replay_scope", "source_model", "block"}
+ or payload.get("protocol") != "anthropic_messages"
+ or payload.get("replay_scope") != replay_scope
+ or not isinstance(payload.get("source_model"), str)
+ or not payload["source_model"]
+ ):
+ raise ResponsesConversionError(
+ "Native reasoning replay has incompatible provenance."
+ )
+ return _validate_block(payload.get("block"))
+
+
+def reject_messages_reasoning_for_other_egress(value: JsonValue) -> None:
+ """Prevent routing native signatures into a different reasoning protocol."""
+
+ items: Sequence[JsonValue]
+ if isinstance(value, Mapping):
+ items = (value,)
+ elif isinstance(value, Sequence) and not isinstance(value, str | bytes):
+ items = value
+ else:
+ return
+ for item in items:
+ if (
+ isinstance(item, Mapping)
+ and item.get("type") == "reasoning"
+ and is_messages_reasoning_carrier(item.get("encrypted_content"))
+ ):
+ raise ResponsesConversionError(
+ "Native Messages reasoning history requires a Messages upstream model."
+ )
diff --git a/src/free_claude_code/core/openai_responses/streaming/completion.py b/src/free_claude_code/core/openai_responses/streaming/completion.py
index adbc7d5d..12b66614 100644
--- a/src/free_claude_code/core/openai_responses/streaming/completion.py
+++ b/src/free_claude_code/core/openai_responses/streaming/completion.py
@@ -148,7 +148,12 @@ def reasoning_output_item(
state: ReasoningBlockState, *, status: str
) -> dict[str, object]:
if state.encrypted_content is not None:
- return encrypted_reasoning_item(state.item_id, state.encrypted_content, status)
+ item = encrypted_reasoning_item(state.item_id, state.encrypted_content, status)
+ if state.text_parts:
+ item["content"] = [
+ {"type": "reasoning_text", "text": "".join(state.text_parts)}
+ ]
+ return item
return reasoning_item(state.item_id, "".join(state.text_parts), status)
diff --git a/src/free_claude_code/providers/anthropic_messages/__init__.py b/src/free_claude_code/providers/anthropic_messages/__init__.py
new file mode 100644
index 00000000..d0658836
--- /dev/null
+++ b/src/free_claude_code/providers/anthropic_messages/__init__.py
@@ -0,0 +1 @@
+"""Shared native Anthropic Messages upstream execution."""
diff --git a/src/free_claude_code/providers/anthropic_messages/request_policy.py b/src/free_claude_code/providers/anthropic_messages/request_policy.py
new file mode 100644
index 00000000..7189442a
--- /dev/null
+++ b/src/free_claude_code/providers/anthropic_messages/request_policy.py
@@ -0,0 +1,162 @@
+"""Resolve native Messages controls from explicit intent and model metadata."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+from free_claude_code.core.anthropic.models import ThinkingConfig
+from free_claude_code.core.anthropic.native import (
+ NativeMessagesError,
+ NativeMessagesOptions,
+)
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.reasoning import ReasoningControl, ReasoningPolicy
+
+DEFAULT_MESSAGES_OUTPUT_TOKENS = 8192
+_MIN_THINKING_BUDGET = 1024
+_NATIVE_EFFORTS = frozenset({"low", "medium", "high", "xhigh", "max"})
+
+
+@dataclass(frozen=True, slots=True)
+class MessagesModelCapabilities:
+ """Unknown metadata stays unknown rather than being inferred from names."""
+
+ max_output_tokens: int | None = None
+ adaptive_thinking: Literal["unsupported", "optional", "required"] | None = None
+ supports_output_effort: bool | None = None
+ supported_efforts: tuple[str, ...] | None = None
+ supports_vision: bool | None = None
+
+ def __post_init__(self) -> None:
+ if self.max_output_tokens is not None and (
+ not isinstance(self.max_output_tokens, int)
+ or isinstance(self.max_output_tokens, bool)
+ or self.max_output_tokens <= 0
+ ):
+ raise ValueError("Advertised output cap must be a positive integer.")
+
+
+def resolve_messages_options(
+ *,
+ model: str,
+ max_tokens: int | None,
+ reasoning: ReasoningPolicy,
+ capabilities: MessagesModelCapabilities = MessagesModelCapabilities(),
+ thinking: ThinkingConfig | None = None,
+ output_effort: object = None,
+) -> NativeMessagesOptions:
+ """Encode supported controls without conflating effort and thinking mode."""
+
+ if output_effort is not None:
+ if not isinstance(
+ output_effort, str
+ ) or output_effort.strip().lower() not in _NATIVE_EFFORTS | {"minimal", "none"}:
+ raise NativeMessagesError("Unsupported client output effort.")
+ output_effort = output_effort.strip().lower()
+ limit = DEFAULT_MESSAGES_OUTPUT_TOKENS if max_tokens is None else max_tokens
+ if not isinstance(limit, int) or isinstance(limit, bool) or limit <= 0:
+ raise NativeMessagesError("Messages max_tokens must be a positive integer.")
+ if capabilities.max_output_tokens is not None:
+ limit = min(limit, capabilities.max_output_tokens)
+ native_mode = thinking.type if thinking is not None else None
+ if thinking is not None:
+ if thinking.model_extra:
+ raise NativeMessagesError("Unsupported native thinking option.")
+ if native_mode not in {None, "enabled", "disabled", "adaptive"}:
+ raise NativeMessagesError(
+ f"Unsupported Messages thinking type: {native_mode!r}"
+ )
+ if thinking.budget_tokens is not None and thinking.budget_tokens <= 0:
+ raise NativeMessagesError("Thinking budget must be a positive integer.")
+ budget = reasoning.budget_tokens
+ # The application owns intent. A native mode is only a wire-format hint.
+ if reasoning.control is ReasoningControl.OFF:
+ mode = "disabled"
+ elif not reasoning.requests_reasoning or native_mode in {"enabled", "adaptive"}:
+ mode = native_mode
+ elif capabilities.adaptive_thinking in {"optional", "required"}:
+ mode = "enabled" if budget is not None else "adaptive"
+ elif capabilities.adaptive_thinking == "unsupported":
+ mode = "enabled"
+ elif reasoning.control is ReasoningControl.DEFAULT and budget is None:
+ mode = None
+ else:
+ raise NativeMessagesError(
+ "This model does not advertise its thinking mode. Supply native "
+ "thinking.type or use an advertised reasoning effort without forcing thinking."
+ )
+ if mode == "adaptive" and capabilities.adaptive_thinking == "unsupported":
+ raise NativeMessagesError("This model does not support adaptive thinking.")
+ if mode == "enabled" and capabilities.adaptive_thinking == "required":
+ raise NativeMessagesError(
+ "This model requires adaptive rather than manual thinking."
+ )
+ if mode == "adaptive" and (
+ budget is not None
+ or (thinking is not None and thinking.budget_tokens is not None)
+ ):
+ raise NativeMessagesError(
+ "Adaptive thinking cannot represent an exact token budget."
+ )
+
+ wire_thinking: JsonObject | None = None
+ if mode is not None:
+ wire_thinking = {"type": mode}
+ if mode == "enabled":
+ exact = budget
+ if (
+ exact is None
+ and thinking is not None
+ and not reasoning.requests_reasoning
+ ):
+ exact = thinking.budget_tokens
+ derived = max(_MIN_THINKING_BUDGET, reasoning.numeric_budget_tokens or 2048)
+ effective = exact if exact is not None else min(derived, limit - 1)
+ if effective < _MIN_THINKING_BUDGET or effective >= limit:
+ raise NativeMessagesError(
+ "Manual thinking budget must be at least 1024 and below max_tokens."
+ )
+ wire_thinking["budget_tokens"] = effective
+ if mode != "disabled" and thinking is not None and thinking.display is not None:
+ wire_thinking["display"] = thinking.display
+
+ effort = (
+ reasoning.effort.value
+ if reasoning.effort is not None
+ else output_effort
+ if reasoning.control is ReasoningControl.DEFAULT
+ else None
+ )
+ if effort == "none" and reasoning.control is ReasoningControl.OFF:
+ effort = None
+ if (
+ mode == "enabled"
+ and capabilities.supports_output_effort is False
+ and reasoning.effort is not None
+ ):
+ effort = None # Already represented by the resolved manual token budget.
+ if effort is not None and (not isinstance(effort, str) or not effort.strip()):
+ raise NativeMessagesError("Messages output effort must be a nonempty string.")
+ if isinstance(effort, str):
+ supported = capabilities.supported_efforts
+ if effort == "minimal" and supported is not None and "low" in supported:
+ effort = "low"
+ if effort == "minimal" or (supported is None and effort not in _NATIVE_EFFORTS):
+ raise NativeMessagesError(
+ f"This model does not advertise a native mapping for effort {effort!r}."
+ )
+ if supported is not None and effort not in supported:
+ raise NativeMessagesError(f"This model does not support effort {effort!r}.")
+ if capabilities.supports_output_effort is False:
+ raise NativeMessagesError("This model does not support output effort.")
+ elif (
+ capabilities.supports_output_effort is None
+ and supported is None
+ and native_mode is None
+ and mode is None
+ ):
+ raise NativeMessagesError(
+ "This model does not advertise output effort support."
+ )
+ return NativeMessagesOptions(
+ model=model, max_tokens=limit, thinking=wire_thinking, output_effort=effort
+ )
diff --git a/src/free_claude_code/providers/anthropic_messages/transport.py b/src/free_claude_code/providers/anthropic_messages/transport.py
new file mode 100644
index 00000000..911a951a
--- /dev/null
+++ b/src/free_claude_code/providers/anthropic_messages/transport.py
@@ -0,0 +1,444 @@
+"""Native Messages HTTP execution with one admitted recovery budget."""
+
+import asyncio
+import sys
+from collections.abc import AsyncIterator, Callable, Mapping
+from typing import cast
+
+import httpx
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.core.anthropic.errors import anthropic_status_for_error_type
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.native import (
+ NativeMessagesError,
+ PreparedMessagesRequest,
+ build_native_messages_request,
+)
+from free_claude_code.core.anthropic.native_stream import NativeMessagesRelay
+from free_claude_code.core.anthropic.streaming.decoder import AnthropicSSEDecoder
+from free_claude_code.core.diagnostics import (
+ ERROR_DETAIL_DISPLAY_CAP_BYTES,
+ attach_upstream_error_body,
+ redact_sensitive_error_text,
+)
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.openai_responses import (
+ AnthropicToResponsesStream,
+ MessagesReplayOrigin,
+ OpenAIResponsesRequest,
+ ResponsesConversionError,
+ ResponsesMessagesRequest,
+ build_responses_messages_request,
+)
+from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.core.trace import trace_event
+from free_claude_code.providers.admission import (
+ ProviderAdmissionController,
+ ProviderCorrectionAction,
+ ProviderExecution,
+ ProviderOperationKind,
+)
+from free_claude_code.providers.endpoint import EndpointContext
+from free_claude_code.providers.failure_policy import (
+ RetryableProviderProtocolError,
+ classify_provider_failure,
+ context_window_exceeded_provider_failure,
+ is_context_window_error_code,
+ is_context_window_finish_reason,
+ is_retryable_stream_error,
+)
+from free_claude_code.providers.http import ProviderAttemptScope, maybe_await_aclose
+from free_claude_code.providers.stream_recovery import (
+ RecoveryController,
+ RecoveryFailureAction,
+)
+
+from .request_policy import MessagesModelCapabilities, resolve_messages_options
+
+type _Presenter = NativeMessagesRelay | AnthropicToResponsesStream
+
+
+class AnthropicMessagesTransport:
+ """Borrow HTTP, endpoint and admission owners; retain each response until closed."""
+
+ def __init__(
+ self,
+ *,
+ client: httpx.AsyncClient,
+ admission: ProviderAdmissionController,
+ provider_name: str,
+ replay_scope: str,
+ read_timeout_s: float,
+ capabilities: MessagesModelCapabilities = MessagesModelCapabilities(),
+ ) -> None:
+ self._client = client
+ self._admission = admission
+ self._provider_name = provider_name
+ self._replay_scope = replay_scope
+ self._read_timeout_s = read_timeout_s
+ self._capabilities = capabilities
+
+ def _messages_body(
+ self, request: MessagesRequest, reasoning: ReasoningPolicy
+ ) -> PreparedMessagesRequest:
+ try:
+ options = resolve_messages_options(
+ model=request.model,
+ max_tokens=request.max_tokens,
+ reasoning=reasoning,
+ capabilities=self._capabilities,
+ thinking=request.thinking,
+ output_effort=request.output_config.get("effort")
+ if request.output_config
+ else None,
+ )
+ return build_native_messages_request(request, options=options)
+ except (NativeMessagesError, ValueError) as error:
+ raise InvalidRequestError(str(error)) from error
+
+ def _responses_body(
+ self, request: OpenAIResponsesRequest, reasoning: ReasoningPolicy
+ ) -> ResponsesMessagesRequest:
+ try:
+ options = resolve_messages_options(
+ model=request.model,
+ max_tokens=request.max_output_tokens,
+ reasoning=reasoning,
+ capabilities=self._capabilities,
+ output_effort=request.reasoning.get("effort")
+ if request.reasoning
+ else None,
+ )
+ return build_responses_messages_request(
+ request, options=options, replay_scope=self._replay_scope
+ )
+ except (NativeMessagesError, ResponsesConversionError, ValueError) as error:
+ raise InvalidRequestError(str(error)) from error
+
+ def preflight_messages(
+ self,
+ request: MessagesRequest,
+ *,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> None:
+ self._messages_body(request, reasoning)
+
+ def preflight_responses(
+ self,
+ request: OpenAIResponsesRequest,
+ *,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> None:
+ self._responses_body(request, reasoning)
+
+ def stream_messages(
+ self,
+ request: MessagesRequest,
+ *,
+ endpoint_context: EndpointContext,
+ request_id: str | None = None,
+ response_model: str | None = None,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> AsyncIterator[str]:
+ prepared = self._messages_body(request, reasoning)
+ return self._stream(
+ prepared.body,
+ betas=prepared.betas,
+ endpoint_context=endpoint_context,
+ request_id=request_id,
+ presenter_factory=lambda: NativeMessagesRelay(
+ public_model=response_model or request.model
+ ),
+ )
+
+ def stream_responses(
+ self,
+ request: OpenAIResponsesRequest,
+ *,
+ endpoint_context: EndpointContext,
+ request_id: str | None = None,
+ response_model: str | None = None,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> AsyncIterator[str]:
+ prepared = self._responses_body(request, reasoning)
+ return self._stream(
+ prepared.body,
+ betas=(),
+ endpoint_context=endpoint_context,
+ request_id=request_id,
+ presenter_factory=lambda: AnthropicToResponsesStream(
+ request,
+ public_model=response_model or request.model,
+ tool_identities=prepared.tool_identities,
+ replay_origin=MessagesReplayOrigin(self._replay_scope, request.model),
+ ),
+ )
+
+ async def _stream(
+ self,
+ body: JsonObject,
+ *,
+ betas: tuple[str, ...],
+ endpoint_context: EndpointContext,
+ request_id: str | None,
+ presenter_factory: Callable[[], _Presenter],
+ ) -> AsyncIterator[str]:
+ execution = self._admission.start_execution(request_id=request_id)
+ run = self._run(
+ body,
+ betas=betas,
+ endpoint_context=endpoint_context,
+ execution=execution,
+ presenter_factory=presenter_factory,
+ )
+ try:
+ async for event in run:
+ yield event
+ except asyncio.CancelledError, GeneratorExit:
+ raise
+ except Exception as error:
+ execution.fail(error)
+ raise
+ else:
+ execution.succeed()
+ finally:
+ await maybe_await_aclose(run)
+ execution.abandon()
+
+ async def _run(
+ self,
+ body: JsonObject,
+ *,
+ betas: tuple[str, ...],
+ endpoint_context: EndpointContext,
+ execution: ProviderExecution,
+ presenter_factory: Callable[[], _Presenter],
+ ) -> AsyncIterator[str]:
+ recovery = RecoveryController()
+ refreshed = False
+ force_refresh = False
+ while execution.can_attempt:
+ presenter = presenter_factory()
+ scope: ProviderAttemptScope | None = None
+ stream_opened = False
+ try:
+ attempt = await execution.open_attempt(ProviderOperationKind.GENERATION)
+ scope = ProviderAttemptScope(
+ attempt,
+ provider_name=self._provider_name,
+ request_id=execution.request_id,
+ )
+ endpoint = await endpoint_context.endpoint(force_refresh=force_refresh)
+ force_refresh = False
+ headers = httpx.Headers(
+ {
+ "anthropic-version": "2023-06-01",
+ "Accept": "text/event-stream",
+ }
+ )
+ headers.update(endpoint.headers)
+ if endpoint.api_key and not any(
+ key.lower() in {"authorization", "x-api-key"} for key in headers
+ ):
+ headers["x-api-key"] = endpoint.api_key
+ if betas:
+ existing = headers.pop("anthropic-beta", "")
+ headers["anthropic-beta"] = ",".join(
+ dict.fromkeys([*filter(None, existing.split(",")), *betas])
+ )
+ base_url = endpoint.base_url.rstrip("/")
+ path = "/messages" if base_url.endswith("/v1") else "/v1/messages"
+ response = scope.retain(
+ await self._client.send(
+ self._client.build_request(
+ "POST",
+ f"{base_url}{path}",
+ json=body,
+ headers=headers,
+ ),
+ stream=True,
+ )
+ )
+ if not response.is_success:
+ raise await _status_error(response)
+ content_type = response.headers.get("content-type", "")
+ if "text/event-stream" not in content_type.lower():
+ raise RetryableProviderProtocolError(
+ "Messages upstream did not return an SSE stream."
+ )
+ stream_opened = True
+ async for event_type, payload in _events(response):
+ _check_failure(event_type, payload)
+ output = presenter.feed(event_type, payload)
+ if event_type != "ping" and not attempt.accepted:
+ await attempt.accept()
+ for event in (output,) if isinstance(output, str) else output:
+ for held in recovery.push(event):
+ yield held
+ if presenter.completed:
+ break
+ if not presenter.completed:
+ raise RetryableProviderProtocolError(
+ "Messages stream ended without message_stop."
+ )
+ for event in recovery.flush():
+ yield event
+ return
+ except asyncio.CancelledError, GeneratorExit:
+ raise
+ except Exception as raw_error:
+ error = (
+ RetryableProviderProtocolError(str(raw_error))
+ if isinstance(raw_error, NativeMessagesError)
+ else raw_error
+ )
+ status = (
+ error.response.status_code
+ if isinstance(error, httpx.HTTPStatusError)
+ else error.status_code
+ if isinstance(error, ExecutionFailure)
+ else None
+ )
+ if (
+ scope is not None
+ and status in {401, 403}
+ and not refreshed
+ and not recovery.committed
+ ):
+ retry = (
+ execution.can_attempt
+ if scope.attempt.accepted
+ else await scope.attempt.correct(error)
+ is ProviderCorrectionAction.RETRY
+ )
+ if retry:
+ refreshed = force_refresh = True
+ recovery.discard()
+ continue
+ attempt_failure = None
+ if scope is not None and not scope.attempt.accepted:
+ attempt_failure = await scope.attempt.fail(error)
+ if attempt_failure is not None and attempt_failure.retry_allowed:
+ recovery.discard()
+ continue
+ decision = recovery.advance_failure(
+ retryable=attempt_failure.retryable
+ if attempt_failure is not None
+ else is_retryable_stream_error(error),
+ stream_opened=stream_opened,
+ generated_output=recovery.committed,
+ complete_tool_salvageable=False,
+ attempts_remaining=execution.attempts_remaining,
+ )
+ if decision.action is RecoveryFailureAction.EARLY_RETRY:
+ recovery.discard()
+ continue
+ failure = classify_provider_failure(
+ error,
+ provider_name=self._provider_name,
+ read_timeout_s=self._read_timeout_s,
+ request_id=execution.request_id,
+ )
+ trace_event(
+ stage="provider",
+ event="provider.response.error",
+ source="provider",
+ provider=self._provider_name,
+ request_id=execution.request_id,
+ transport="messages",
+ failure_kind=failure.kind.value,
+ )
+ if decision.committed and isinstance(
+ presenter, AnthropicToResponsesStream
+ ):
+ execution.fail(failure)
+ for event in presenter.terminal_failure(failure):
+ yield event
+ return
+ recovery.discard()
+ raise failure from raw_error
+ finally:
+ if scope is not None:
+ await scope.aclose(active_error=sys.exception())
+ if execution.last_failure is not None:
+ raise execution.last_failure
+ raise RuntimeError("Messages execution ended without a terminal result.")
+
+
+async def _events(response: httpx.Response) -> AsyncIterator[tuple[str, JsonObject]]:
+ decoder = AnthropicSSEDecoder()
+ async for chunk in response.aiter_text():
+ for event in decoder.feed(chunk):
+ payload = cast(JsonObject, event.data)
+ kind = event.event or payload.get("type")
+ if not isinstance(kind, str) or not kind:
+ raise RetryableProviderProtocolError(
+ "Messages stream has an invalid event type."
+ )
+ yield kind, payload
+ for event in decoder.finish():
+ payload = cast(JsonObject, event.data)
+ kind = event.event or payload.get("type")
+ if not isinstance(kind, str) or not kind:
+ raise RetryableProviderProtocolError(
+ "Messages stream has an invalid final event."
+ )
+ yield kind, payload
+
+
+def _check_failure(event_type: str, payload: JsonObject) -> None:
+ delta = payload.get("delta")
+ if (
+ event_type == "message_delta"
+ and isinstance(delta, Mapping)
+ and is_context_window_finish_reason(delta.get("stop_reason"))
+ ):
+ raise context_window_exceeded_provider_failure()
+ if event_type != "error":
+ return
+ error = payload.get("error")
+ kind = error.get("type") if isinstance(error, Mapping) else None
+ if isinstance(error, Mapping) and any(
+ is_context_window_error_code(error.get(key)) for key in ("type", "code")
+ ):
+ raise context_window_exceeded_provider_failure()
+ status = anthropic_status_for_error_type(kind if isinstance(kind, str) else "")
+ failure_kind = {
+ 400: FailureKind.INVALID_REQUEST,
+ 401: FailureKind.AUTHENTICATION,
+ 402: FailureKind.PERMISSION,
+ 403: FailureKind.PERMISSION,
+ 404: FailureKind.INVALID_REQUEST,
+ 413: FailureKind.INVALID_REQUEST,
+ 429: FailureKind.RATE_LIMIT,
+ 504: FailureKind.TIMEOUT,
+ 529: FailureKind.OVERLOADED,
+ }.get(status, FailureKind.UPSTREAM)
+ message = error.get("message") if isinstance(error, Mapping) else None
+ raise ExecutionFailure(
+ failure_kind,
+ status,
+ redact_sensitive_error_text(message[:ERROR_DETAIL_DISPLAY_CAP_BYTES])
+ if isinstance(message, str) and message
+ else "Messages upstream returned an error.",
+ status == 429 or status >= 500,
+ )
+
+
+async def _status_error(response: httpx.Response) -> httpx.HTTPStatusError:
+ limit = ERROR_DETAIL_DISPLAY_CAP_BYTES
+ body = bytearray()
+ async for chunk in response.aiter_bytes():
+ body.extend(chunk[: limit + 1 - len(body)])
+ if len(body) > limit:
+ break
+ try:
+ response.raise_for_status()
+ except httpx.HTTPStatusError as error:
+ attach_upstream_error_body(
+ error, bytes(body[:limit]), truncated=len(body) > limit
+ )
+ return error
+ raise AssertionError("Expected an unsuccessful Messages response.")
diff --git a/src/free_claude_code/providers/endpoint.py b/src/free_claude_code/providers/endpoint.py
new file mode 100644
index 00000000..e6edf458
--- /dev/null
+++ b/src/free_claude_code/providers/endpoint.py
@@ -0,0 +1,122 @@
+"""Request-scoped endpoint snapshots borrowed by provider transports."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import httpx
+import httpx2
+from openai import AsyncOpenAI, Omit
+
+from free_claude_code.providers.admission import (
+ ProviderAttempt,
+ ProviderCorrectionAction,
+ ProviderExecution,
+)
+from free_claude_code.providers.failure_policy import provider_authentication_status
+
+
+@dataclass(frozen=True, slots=True)
+class HttpEndpoint:
+ """A resolved API root and credentials; callers own validation and lifetime."""
+
+ base_url: str
+ headers: Mapping[str, str] = field(repr=False)
+ api_key: str | None = field(default=None, repr=False)
+
+
+class EndpointContext(Protocol):
+ """Borrow a current snapshot without changing credentials on shared clients."""
+
+ async def endpoint(self, *, force_refresh: bool = False) -> HttpEndpoint: ...
+
+
+class _BorrowedTransport(httpx2.AsyncBaseTransport):
+ """Share connections while the provider generation retains pool ownership."""
+
+ def __init__(self, transport: httpx2.AsyncBaseTransport) -> None:
+ self._transport = transport
+
+ async def handle_async_request(self, request: httpx2.Request) -> httpx2.Response:
+ return await self._transport.handle_async_request(request)
+
+
+class RequestEndpoint:
+ """Resolve one request's credentials and permit one refresh before commitment."""
+
+ def __init__(
+ self,
+ context: EndpointContext,
+ transport: httpx2.AsyncBaseTransport | None = None,
+ ) -> None:
+ self._context = context
+ self._transport = transport
+ self._http: httpx2.AsyncClient | None = None
+ self._refreshed = False
+ self._refresh_pending = False
+ self._committed = False
+ self._omit_authorization = False
+
+ def commit(self) -> None:
+ self._committed = True
+
+ async def aclose(self) -> None:
+ if self._http is not None:
+ await self._http.aclose()
+
+ async def openai_client(self, client: AsyncOpenAI) -> AsyncOpenAI:
+ endpoint = await self._context.endpoint(force_refresh=self._refresh_pending)
+ self._refresh_pending = False
+ if self._http is None:
+ self._http = httpx2.AsyncClient(
+ transport=_BorrowedTransport(self._transport)
+ if self._transport is not None
+ else None,
+ follow_redirects=False,
+ )
+ # An endpoint is authoritative for every attempt, including after refresh.
+ self._http.cookies.clear()
+ headers = dict(httpx.Headers(endpoint.headers).items())
+ self._omit_authorization = (
+ endpoint.api_key is None and "authorization" not in headers
+ )
+ if "authorization" in headers:
+ headers["Authorization"] = headers.pop("authorization")
+
+ async def credential() -> str:
+ # A callable also overrides an inherited key with an empty credential.
+ return endpoint.api_key or ""
+
+ view = client.with_options(
+ api_key=credential,
+ base_url=endpoint.base_url,
+ set_default_headers=headers,
+ set_default_query={},
+ http_client=self._http,
+ max_retries=0,
+ )
+ # SDK copy(None) inherits these values. Clear only this owned view.
+ view.organization = None
+ view.project = None
+ view.admin_api_key = None
+ return view
+
+ def openai_headers(self) -> dict[str, str | Omit]:
+ return {"Authorization": Omit()} if self._omit_authorization else {}
+
+ async def retry_authentication(
+ self, error: Exception, attempt: ProviderAttempt, execution: ProviderExecution
+ ) -> bool:
+ if self._refreshed or self._committed:
+ return False
+ status = provider_authentication_status(error)
+ if status not in {401, 403}:
+ return False
+ allowed = (
+ execution.can_attempt
+ if attempt.accepted
+ else await attempt.correct(error) is ProviderCorrectionAction.RETRY
+ )
+ if allowed:
+ self._refreshed = self._refresh_pending = True
+ return allowed
diff --git a/src/free_claude_code/providers/failure_policy.py b/src/free_claude_code/providers/failure_policy.py
index 4029fed1..8ca3ddcb 100644
--- a/src/free_claude_code/providers/failure_policy.py
+++ b/src/free_claude_code/providers/failure_policy.py
@@ -9,6 +9,7 @@ from typing import Any
import httpx
import openai
+from free_claude_code.core.anthropic.errors import anthropic_status_for_error_type
from free_claude_code.core.diagnostics import (
attached_upstream_error_body,
extract_upstream_error_detail,
@@ -104,6 +105,27 @@ def overloaded_provider_failure() -> ExecutionFailure:
return _failure(FailureKind.OVERLOADED, 529, _OVERLOADED_MESSAGE, True)
+def provider_authentication_status(exc: Exception) -> int | None:
+ """Recognize HTTP and structured stream authentication failures, never prose."""
+ status = _reported_status(exc)
+ if status is not None:
+ return status if status in {401, 403} else None
+ codes: list[object] = [getattr(exc, "code", None)]
+ for item in _body_candidates(getattr(exc, "body", None)):
+ if isinstance(item, Mapping):
+ codes.extend((item.get("code"), item.get("type")))
+ for code in codes:
+ if isinstance(code, str) and (
+ status := anthropic_status_for_error_type(code)
+ ) in {401, 403}:
+ return status
+ if any(code in ("invalid_api_key", "unauthorized") for code in codes):
+ return 401
+ if any(code in ("permission_denied", "forbidden") for code in codes):
+ return 403
+ return None
+
+
def context_window_exceeded_provider_failure(
message: str = _CONTEXT_WINDOW_EXCEEDED_MESSAGE,
) -> ExecutionFailure:
@@ -315,9 +337,9 @@ def _classify_provider_failure(
False,
)
- if isinstance(exc, openai.AuthenticationError):
+ if provider_authentication_status(exc) == 401:
return _failure(FailureKind.AUTHENTICATION, 401, _AUTHENTICATION_MESSAGE, False)
- if isinstance(exc, openai.PermissionDeniedError):
+ if provider_authentication_status(exc) == 403:
return _failure(FailureKind.PERMISSION, 403, _PERMISSION_MESSAGE, False)
if isinstance(exc, openai.RateLimitError):
return _failure(FailureKind.RATE_LIMIT, 429, _RATE_LIMIT_MESSAGE, True)
diff --git a/src/free_claude_code/providers/github_copilot/__init__.py b/src/free_claude_code/providers/github_copilot/__init__.py
new file mode 100644
index 00000000..dff57c99
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/__init__.py
@@ -0,0 +1 @@
+"""GitHub Copilot account, endpoint and provider owners."""
diff --git a/src/free_claude_code/providers/github_copilot/auth.py b/src/free_claude_code/providers/github_copilot/auth.py
new file mode 100644
index 00000000..ee494fb8
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/auth.py
@@ -0,0 +1,467 @@
+"""Opt-in FCC connection state over native Copilot account credentials."""
+
+import asyncio
+import json
+import os
+import tempfile
+import time
+import uuid
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from free_claude_code.application.connected_accounts import (
+ ConnectedAccountLoginMode,
+ ConnectedAccountState,
+ ConnectedAccountStatus,
+)
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.config.paths import github_copilot_auth_path
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.providers.endpoint import HttpEndpoint
+
+from .broker import CopilotBroker, CopilotLease
+from .lifecycle import drain_owned
+from .login import LOGIN_TIMEOUT_SECONDS, DeviceChallenge, device_login
+from .sdk import SdkRuntime
+from .types import (
+ CopilotAuthenticationRequired,
+ CopilotEgress,
+ CopilotIdentity,
+ CopilotModel,
+ CopilotRuntime,
+ CopilotUnavailable,
+)
+
+LoginFlow = Callable[[Callable[[DeviceChallenge], None]], Awaitable[None]]
+
+
+class AuthenticatedLease:
+ """Map account loss at credential resolution to a canonical provider failure."""
+
+ def __init__(
+ self,
+ manager: CopilotAuthManager,
+ broker: CopilotBroker,
+ lease: CopilotLease,
+ revision: int,
+ ) -> None:
+ self._manager = manager
+ self._broker = broker
+ self._lease = lease
+ self._revision = revision
+
+ @property
+ def model(self) -> CopilotModel:
+ return self._lease.model
+
+ @property
+ def egress(self) -> CopilotEgress:
+ return self._lease.egress
+
+ async def endpoint(self, *, force_refresh: bool = False) -> HttpEndpoint:
+ try:
+ self._manager.ensure_current(self._broker, self._revision)
+ endpoint = await self._lease.endpoint(force_refresh=force_refresh)
+ self._manager.ensure_current(self._broker, self._revision)
+ return endpoint
+ except CopilotUnavailable as error:
+ raise self._manager.account_failure(
+ error, self._broker, self._revision
+ ) from None
+
+
+class CopilotAuthManager:
+ """Own enabled state, login attempts, account revisions and draining brokers."""
+
+ provider_id = "github_copilot"
+
+ def __init__(
+ self,
+ *,
+ state_path: Path | None = None,
+ runtime_factory: Callable[[], CopilotRuntime] = SdkRuntime,
+ login_flow: LoginFlow = device_login,
+ login_timeout_s: float = LOGIN_TIMEOUT_SECONDS,
+ ) -> None:
+ self._state_path = state_path or github_copilot_auth_path()
+ self._runtime_factory = runtime_factory
+ self._login_flow = login_flow
+ self._login_timeout_s = login_timeout_s
+ self._enabled = False
+ self._identity: CopilotIdentity | None = None
+ self._revision = 0
+ self._last_error: str | None = None
+ self._broker: CopilotBroker | None = None
+ self._owners: list[CopilotBroker] = []
+ self._operation_lock = asyncio.Lock()
+ self._login_task: asyncio.Task[None] | None = None
+ self._cleanup_task: asyncio.Task[None] | None = None
+ self._close_task: asyncio.Task[None] | None = None
+ self._attempt_id: str | None = None
+ self._challenge: DeviceChallenge | None = None
+ self._expires_at: int | None = None
+ self._closed = False
+ try:
+ self._read_state()
+ except OSError, ValueError, UnicodeError:
+ self._enabled = False
+ self._identity = None
+ self._last_error = (
+ "Saved Copilot connection state is unreadable. Connect again."
+ )
+
+ def is_connected(self) -> bool:
+ return self._enabled and not self._closed
+
+ def connected_provider_ids(self) -> tuple[str, ...]:
+ return (self.provider_id,) if self.is_connected() else ()
+
+ def status(self) -> ConnectedAccountStatus:
+ connecting = self._login_task is not None and not self._login_task.done()
+ state = (
+ ConnectedAccountState.CONNECTING
+ if connecting
+ else ConnectedAccountState.ERROR
+ if self._last_error
+ else ConnectedAccountState.CONNECTED
+ if self.is_connected()
+ else ConnectedAccountState.DISCONNECTED
+ )
+ challenge = self._challenge if connecting else None
+ return ConnectedAccountStatus(
+ provider_id=self.provider_id,
+ state=state,
+ connected=self.is_connected(),
+ revision=self._revision,
+ display_identity=self._identity.display
+ if self._identity is not None
+ else None,
+ supported_login_modes=(ConnectedAccountLoginMode.DEVICE,),
+ default_login_mode=ConnectedAccountLoginMode.DEVICE,
+ attempt_id=self._attempt_id if connecting else None,
+ mode=ConnectedAccountLoginMode.DEVICE if connecting else None,
+ verification_url=challenge.verification_url if challenge else None,
+ user_code=challenge.user_code if challenge else None,
+ expires_at=self._expires_at if connecting else None,
+ model_count=len(self._broker.current_models) if self._broker else 0,
+ message=self._last_error,
+ )
+
+ async def start_login(
+ self, mode: ConnectedAccountLoginMode
+ ) -> ConnectedAccountStatus:
+ if mode is not ConnectedAccountLoginMode.DEVICE:
+ raise InvalidRequestError("Copilot supports device-code login.")
+ async with self._operation_lock:
+ self._ensure_open()
+ if self._login_task is not None and not self._login_task.done():
+ return self.status()
+ # Reconnect stops new requests under the old revision immediately.
+ if not self._disable():
+ return self.status()
+ self._last_error = None
+ attempt = uuid.uuid4().hex
+ self._attempt_id = attempt
+ self._challenge = None
+ self._expires_at = int(time.time() + self._login_timeout_s)
+ self._login_task = asyncio.create_task(self._complete_login(attempt))
+ return self.status()
+
+ async def cancel_login(self) -> ConnectedAccountStatus:
+ async with self._operation_lock:
+ await self._cancel_login()
+ try:
+ await self._drain_retired()
+ except CopilotUnavailable:
+ self._last_error = "Copilot cleanup could not finish. Retry Connect to close the previous attempt."
+ else:
+ self._last_error = None
+ return self.status()
+
+ async def disconnect(self) -> ConnectedAccountStatus:
+ async with self._operation_lock:
+ self._ensure_open()
+ saved = self._disable()
+ await self._cancel_login()
+ await self._drain_retired()
+ if saved:
+ self._last_error = None
+ return self.status()
+
+ async def close(self) -> None:
+ if self._close_task is None or self._close_task.done():
+ self._closed = True
+ self._close_task = asyncio.create_task(self._close())
+ await drain_owned(self._close_task)
+
+ async def _close(self) -> None:
+ async with self._operation_lock:
+ # Preserve opt-in on process shutdown; credentials belong to the CLI.
+ self._broker = None
+ await self._cancel_login()
+ await self._drain_retired()
+
+ def _ensure_open(self) -> None:
+ if self._closed:
+ raise CopilotUnavailable("Copilot account manager is closing.")
+
+ def _new_broker(self, identity: CopilotIdentity | None) -> CopilotBroker:
+ broker = CopilotBroker(self._runtime_factory(), expected_identity=identity)
+ self._owners.append(broker)
+ return broker
+
+ def _current_broker(self) -> CopilotBroker:
+ self._ensure_open()
+ if not self._enabled:
+ raise CopilotAuthenticationRequired(
+ "Connect your GitHub Copilot account in Admin."
+ )
+ if self._broker is None:
+ self._broker = self._new_broker(self._identity)
+ return self._broker
+
+ def ensure_current(self, broker: CopilotBroker, revision: int) -> None:
+ if (
+ not self.is_connected()
+ or broker is not self._broker
+ or revision != self._revision
+ ):
+ raise CopilotAuthenticationRequired(
+ "Copilot connection changed. Retry after connecting in Admin."
+ )
+
+ async def models(self, *, refresh: bool = True) -> Mapping[str, CopilotModel]:
+ broker: CopilotBroker | None = None
+ revision = self._revision
+ try:
+ broker = self._current_broker()
+ models = await broker.snapshot(refresh=refresh)
+ self.ensure_current(broker, revision)
+ return models
+ except CopilotUnavailable as error:
+ raise self.account_failure(error, broker, revision) from None
+
+ @asynccontextmanager
+ async def lease(self, model_id: str) -> AsyncIterator[AuthenticatedLease]:
+ broker: CopilotBroker | None = None
+ revision = self._revision
+ try:
+ broker = self._current_broker()
+ async with broker.lease(model_id) as lease:
+ self.ensure_current(broker, revision)
+ yield AuthenticatedLease(self, broker, lease, revision)
+ except CopilotUnavailable as error:
+ raise self.account_failure(error, broker, revision) from None
+ except ExecutionFailure as error:
+ if error.status_code == 401:
+ self._invalidate(
+ broker,
+ revision,
+ "Copilot rejected refreshed credentials. Reconnect in Admin.",
+ )
+ raise
+
+ def account_failure(
+ self, error: CopilotUnavailable, broker: CopilotBroker | None, revision: int
+ ) -> ExecutionFailure:
+ if isinstance(error, CopilotAuthenticationRequired):
+ self._invalidate(broker, revision, str(error))
+ return ExecutionFailure(FailureKind.AUTHENTICATION, 401, str(error), False)
+ return ExecutionFailure(FailureKind.UNAVAILABLE, 503, str(error), False)
+
+ def _invalidate(
+ self, broker: CopilotBroker | None, revision: int, message: str
+ ) -> None:
+ if self._enabled and revision == self._revision and broker is self._broker:
+ if not self._disable():
+ message += " FCC could not save the disconnected state."
+ self._last_error = message
+
+ def _disable(self) -> bool:
+ self._enabled = False
+ self._identity = None
+ self._broker = None
+ self._revision += 1
+ try:
+ self._write_state(enabled=False, identity=None, revision=self._revision)
+ except OSError:
+ self._last_error = "FCC could not save the disconnected state. Check state-directory permissions and retry Disconnect."
+ return False
+ finally:
+ self._schedule_cleanup()
+ return True
+
+ async def _cancel_login(self) -> None:
+ task = self._login_task
+ self._attempt_id = None
+ self._challenge = None
+ self._expires_at = None
+ if task is not None:
+ task.cancel()
+ # The login owns its cleanup; cancellation waits for that finally block.
+ await drain_owned(asyncio.create_task(_settle(task)))
+ self._login_task = None
+
+ def _schedule_cleanup(self) -> asyncio.Task[None]:
+ if self._cleanup_task is None or self._cleanup_task.done():
+ self._cleanup_task = asyncio.create_task(self._cleanup_retired())
+ self._cleanup_task.add_done_callback(_retrieve_failure)
+ return self._cleanup_task
+
+ async def _drain_retired(self) -> None:
+ await drain_owned(self._schedule_cleanup())
+
+ async def _cleanup_retired(self) -> None:
+ failures = False
+ for broker in tuple(self._owners):
+ if broker is self._broker:
+ continue
+ try:
+ await broker.close()
+ except Exception:
+ failures = True
+ else:
+ if broker in self._owners:
+ self._owners.remove(broker)
+ if failures:
+ raise CopilotUnavailable(
+ "Copilot cleanup could not finish. Retry disconnect."
+ )
+
+ async def _complete_login(self, attempt: str) -> None:
+ broker: CopilotBroker | None = None
+
+ def on_challenge(challenge: DeviceChallenge) -> None:
+ if self._attempt_id == attempt and not self._closed:
+ self._challenge = challenge
+
+ try:
+ async with asyncio.timeout(self._login_timeout_s):
+ await self._drain_retired()
+ broker = self._new_broker(None)
+ try:
+ await broker.snapshot(refresh=True)
+ except CopilotAuthenticationRequired:
+ await broker.close()
+ if broker in self._owners:
+ self._owners.remove(broker)
+ broker = None
+ await self._login_flow(on_challenge)
+ broker = self._new_broker(None)
+ await broker.snapshot(refresh=True)
+ identity = broker.identity
+ if identity is None:
+ raise CopilotAuthenticationRequired(
+ "Copilot did not report a signed-in profile."
+ )
+ if self._attempt_id != attempt or self._closed:
+ return
+ revision = self._revision + 1
+ self._write_state(enabled=True, identity=identity, revision=revision)
+ self._identity = identity
+ self._revision = revision
+ self._enabled = True
+ self._broker = broker
+ self._last_error = None
+ except asyncio.CancelledError:
+ raise
+ except Exception as error:
+ if self._attempt_id == attempt and not self._closed:
+ self._last_error = (
+ "Copilot sign-in exceeded FCC's time limit. Connect again."
+ if isinstance(error, TimeoutError)
+ else str(error)
+ if isinstance(error, CopilotUnavailable)
+ else "Copilot connection failed. Check the CLI installation, selected account and FCC state-directory permissions."
+ )
+ finally:
+ if broker is not None and broker is not self._broker:
+ try:
+ await drain_owned(asyncio.create_task(broker.close()))
+ except Exception:
+ if self._attempt_id == attempt:
+ self._last_error = (
+ "Copilot cleanup could not finish. Retry disconnect."
+ )
+ else:
+ if broker in self._owners:
+ self._owners.remove(broker)
+ if self._login_task is asyncio.current_task():
+ self._login_task = None
+ self._attempt_id = None
+ self._challenge = None
+ self._expires_at = None
+
+ def _read_state(self) -> None:
+ try:
+ payload: object = json.loads(self._state_path.read_text(encoding="utf-8"))
+ except FileNotFoundError:
+ return
+ if not isinstance(payload, dict) or payload.get("schema_version") != 1:
+ raise ValueError("Invalid Copilot state schema")
+ revision = payload.get("revision")
+ enabled = payload.get("enabled")
+ if (
+ not isinstance(revision, int)
+ or isinstance(revision, bool)
+ or revision < 0
+ or not isinstance(enabled, bool)
+ ):
+ raise ValueError("Invalid Copilot state")
+ identity = payload.get("identity")
+ if enabled:
+ if not isinstance(identity, dict):
+ raise ValueError("Missing Copilot identity")
+ host, login = identity.get("host"), identity.get("login")
+ if (
+ not isinstance(host, str)
+ or not host
+ or not isinstance(login, str)
+ or not login
+ ):
+ raise ValueError("Invalid Copilot identity")
+ self._identity = CopilotIdentity(host, login)
+ self._revision = revision
+ self._enabled = enabled
+
+ def _write_state(
+ self, *, enabled: bool, identity: CopilotIdentity | None, revision: int
+ ) -> None:
+ payload: JsonObject = {
+ "schema_version": 1,
+ "enabled": enabled,
+ "revision": revision,
+ "identity": {"host": identity.host, "login": identity.login}
+ if identity
+ else None,
+ }
+ self._state_path.parent.mkdir(parents=True, exist_ok=True)
+ temporary: Path | None = None
+ try:
+ with tempfile.NamedTemporaryFile(
+ mode="w",
+ encoding="utf-8",
+ dir=self._state_path.parent,
+ prefix=".copilot-",
+ suffix=".tmp",
+ delete=False,
+ ) as handle:
+ temporary = Path(handle.name)
+ json.dump(payload, handle)
+ handle.flush()
+ os.fsync(handle.fileno())
+ os.replace(temporary, self._state_path)
+ finally:
+ if temporary is not None:
+ temporary.unlink(missing_ok=True)
+
+
+async def _settle(task: asyncio.Task[None]) -> None:
+ await asyncio.gather(task, return_exceptions=True)
+
+
+def _retrieve_failure(task: asyncio.Task[None]) -> None:
+ if not task.cancelled():
+ task.exception()
diff --git a/src/free_claude_code/providers/github_copilot/broker.py b/src/free_claude_code/providers/github_copilot/broker.py
new file mode 100644
index 00000000..8a9fcf6b
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/broker.py
@@ -0,0 +1,247 @@
+"""Account-scoped discovery and inert endpoint sessions with draining leases."""
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from types import MappingProxyType
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.providers.endpoint import HttpEndpoint
+
+from .lifecycle import drain_owned
+from .types import (
+ CopilotAuthenticationRequired,
+ CopilotEgress,
+ CopilotEndpoint,
+ CopilotIdentity,
+ CopilotModel,
+ CopilotRuntime,
+ CopilotSession,
+ CopilotUnavailable,
+)
+
+_REFRESH_EARLY_SECONDS = 30
+
+
+class _EndpointOwner:
+ def __init__(self, runtime: CopilotRuntime, model_id: str) -> None:
+ self._runtime = runtime
+ self._model_id = model_id
+ self._lock = asyncio.Lock()
+ self._session_task: asyncio.Task[CopilotSession] | None = None
+ self._snapshot: CopilotEndpoint | None = None
+
+ async def endpoint(self, *, force_refresh: bool) -> CopilotEndpoint:
+ async with self._lock:
+ if self._session_task is None or (
+ self._session_task.done()
+ and (
+ self._session_task.cancelled()
+ or self._session_task.exception() is not None
+ )
+ ):
+ self._session_task = asyncio.create_task(
+ self._runtime.session(self._model_id)
+ )
+ session = await asyncio.shield(self._session_task)
+ snapshot = self._snapshot
+ if (
+ force_refresh
+ or snapshot is None
+ or (
+ snapshot.expires_at is not None
+ and snapshot.expires_at <= time.time() + _REFRESH_EARLY_SECONDS
+ )
+ ):
+ snapshot = await session.endpoint()
+ if (
+ snapshot.expires_at is not None
+ and snapshot.expires_at <= time.time()
+ ):
+ raise CopilotUnavailable(
+ "Copilot returned an expired endpoint credential. Reconnect Copilot."
+ )
+ self._snapshot = snapshot
+ return snapshot
+
+ async def drain_creation(self) -> None:
+ if self._session_task is not None:
+ await asyncio.gather(self._session_task, return_exceptions=True)
+
+
+class CopilotLease:
+ """Retain one concrete model and its routing family throughout inference."""
+
+ def __init__(
+ self,
+ broker: CopilotBroker,
+ owner: _EndpointOwner,
+ model: CopilotModel,
+ egress: CopilotEgress,
+ ) -> None:
+ self._broker = broker
+ self._owner = owner
+ self.model = model
+ self.egress = egress
+ self._released = False
+
+ async def endpoint(self, *, force_refresh: bool = False) -> HttpEndpoint:
+ if self._released:
+ raise CopilotUnavailable("Copilot endpoint lease has already closed.")
+ await self._broker.validate_identity()
+ self._broker.validate_model(self.model.info.model_id)
+ snapshot = await self._owner.endpoint(force_refresh=force_refresh)
+ await self._broker.validate_identity()
+ self._broker.validate_model(self.model.info.model_id)
+ if snapshot.egress is not self.egress:
+ raise CopilotUnavailable(
+ "Copilot changed this model's upstream protocol. Retry the request to use its new endpoint."
+ )
+ return snapshot.http
+
+ def release(self) -> None:
+ self._released = True
+
+
+class CopilotBroker:
+ """Coalesce SDK discovery and retain sessions until every response closes."""
+
+ def __init__(
+ self,
+ runtime: CopilotRuntime,
+ *,
+ expected_identity: CopilotIdentity | None = None,
+ ) -> None:
+ self._runtime = runtime
+ self._identity = expected_identity
+ self._models: Mapping[str, CopilotModel] = MappingProxyType({})
+ self._owners: dict[str, _EndpointOwner] = {}
+ self._condition = asyncio.Condition()
+ self._start_task: asyncio.Task[None] | None = None
+ self._refresh_task: asyncio.Task[Mapping[str, CopilotModel]] | None = None
+ self._close_task: asyncio.Task[None] | None = None
+ self._closing = False
+ self._closed = False
+ self._leases = 0
+
+ @property
+ def identity(self) -> CopilotIdentity | None:
+ return self._identity
+
+ @property
+ def current_models(self) -> Mapping[str, CopilotModel]:
+ return self._models
+
+ async def _start(self) -> None:
+ async with self._condition:
+ if self._closing:
+ raise CopilotUnavailable("Copilot connection is closing.")
+ if self._start_task is None:
+ self._start_task = asyncio.create_task(self._runtime.start())
+ task = self._start_task
+ await asyncio.shield(task)
+
+ async def validate_identity(self) -> CopilotIdentity:
+ identity = await self._runtime.identity()
+ if identity is None:
+ raise CopilotAuthenticationRequired(
+ "Copilot is signed out. Connect your GitHub account in Admin."
+ )
+ if self._identity is not None and identity != self._identity:
+ raise CopilotAuthenticationRequired(
+ "The selected GitHub profile changed. Reconnect Copilot in Admin."
+ )
+ self._identity = identity
+ return identity
+
+ async def snapshot(self, *, refresh: bool = False) -> Mapping[str, CopilotModel]:
+ await self._start()
+ await self.validate_identity()
+ async with self._condition:
+ if self._closing:
+ raise CopilotUnavailable("Copilot connection is closing.")
+ task = self._refresh_task
+ if task is None or task.done():
+ if self._models and not refresh:
+ return self._models
+ task = asyncio.create_task(self._discover())
+ self._refresh_task = task
+ return await asyncio.shield(task)
+
+ def validate_model(self, model_id: str) -> CopilotModel:
+ model = self._models.get(model_id)
+ if model is None:
+ raise InvalidRequestError(
+ "This model is not available from the connected Copilot account. Refresh the model list."
+ )
+ return model
+
+ async def _discover(self) -> Mapping[str, CopilotModel]:
+ await self.validate_identity()
+ models = await self._runtime.models()
+ await self.validate_identity()
+ result = {model.info.model_id: model for model in models}
+ if len(result) != len(models):
+ raise CopilotUnavailable("Copilot returned conflicting model identifiers.")
+ async with self._condition:
+ if self._closing:
+ raise CopilotUnavailable("Copilot connection closed during discovery.")
+ self._models = MappingProxyType(result)
+ if not result:
+ raise CopilotUnavailable(
+ "This GitHub account exposes no enabled Copilot models. Check its subscription and model policies."
+ )
+ return self._models
+
+ @asynccontextmanager
+ async def lease(self, model_id: str) -> AsyncIterator[CopilotLease]:
+ await self.snapshot()
+ async with self._condition:
+ if self._closing:
+ raise CopilotUnavailable("Copilot connection is closing.")
+ model = self.validate_model(model_id)
+ self._leases += 1
+ owner = self._owners.get(model_id)
+ if owner is None:
+ owner = _EndpointOwner(self._runtime, model_id)
+ self._owners[model_id] = owner
+ lease = None
+ try:
+ await self.validate_identity()
+ endpoint = await owner.endpoint(force_refresh=False)
+ await self.validate_identity()
+ self.validate_model(model_id)
+ lease = CopilotLease(self, owner, model, endpoint.egress)
+ yield lease
+ finally:
+ if lease is not None:
+ lease.release()
+ async with self._condition:
+ self._leases -= 1
+ self._condition.notify_all()
+
+ async def close(self) -> None:
+ if self._closed:
+ return
+ if self._close_task is None or self._close_task.done():
+ self._closing = True
+ self._close_task = asyncio.create_task(self._close())
+ await drain_owned(self._close_task)
+
+ async def _close(self) -> None:
+ # Stop discovery publication; SDK-owned work itself has bounded RPC timeouts.
+ tasks = [
+ task for task in (self._start_task, self._refresh_task) if task is not None
+ ]
+ if tasks:
+ await asyncio.gather(*tasks, return_exceptions=True)
+ async with self._condition:
+ await self._condition.wait_for(lambda: self._leases == 0)
+ await asyncio.gather(
+ *(owner.drain_creation() for owner in self._owners.values())
+ )
+ await self._runtime.close()
+ self._owners.clear()
+ self._models = MappingProxyType({})
+ self._closed = True
diff --git a/src/free_claude_code/providers/github_copilot/lifecycle.py b/src/free_claude_code/providers/github_copilot/lifecycle.py
new file mode 100644
index 00000000..d1a20a27
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/lifecycle.py
@@ -0,0 +1,18 @@
+"""Drain Copilot-owned work before propagating caller cancellation."""
+
+import asyncio
+
+
+async def drain_owned[T](task: asyncio.Task[T]) -> T:
+ cancelled = False
+ while not task.done():
+ try:
+ await asyncio.shield(task)
+ except asyncio.CancelledError:
+ if task.cancelled():
+ raise
+ cancelled = True
+ result = task.result()
+ if cancelled:
+ raise asyncio.CancelledError
+ return result
diff --git a/src/free_claude_code/providers/github_copilot/login.py b/src/free_claude_code/providers/github_copilot/login.py
new file mode 100644
index 00000000..9bbeff4a
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/login.py
@@ -0,0 +1,112 @@
+"""Official native Copilot device login; FCC never handles the resulting token."""
+
+import asyncio
+import os
+import re
+import subprocess
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+from .lifecycle import drain_owned
+from .sdk import profile_environment, verified_cli_path
+from .types import CopilotUnavailable
+
+LOGIN_TIMEOUT_SECONDS = 15 * 60
+_CHALLENGE = re.compile(
+ r"visit\s+(https://[^\s]+/login/device)\s+and enter code\s+([A-Z0-9]{4}-[A-Z0-9]{4})",
+ re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceChallenge:
+ verification_url: str
+ user_code: str
+
+
+def parse_challenge(text: str) -> DeviceChallenge | None:
+ match = _CHALLENGE.search(text)
+ if match is None:
+ return None
+ url, code = match.groups()
+ parsed = urlsplit(url)
+ if not parsed.hostname or parsed.username or parsed.password:
+ return None
+ return DeviceChallenge(url, code.upper())
+
+
+async def device_login(on_challenge: Callable[[DeviceChallenge], None]) -> None:
+ """Run the pinned CLI login and own its child and both bounded readers."""
+ env = profile_environment()
+ path = await verified_cli_path(env)
+ spawning = asyncio.create_task(
+ asyncio.create_subprocess_exec(
+ path,
+ "login",
+ "--device-code",
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ env=env,
+ creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0,
+ )
+ )
+ readers: list[asyncio.Task[None]] = []
+
+ async def read_output(stream: asyncio.StreamReader) -> None:
+ buffer = ""
+ previous: DeviceChallenge | None = None
+ while chunk := await stream.read(1024):
+ buffer = (buffer + chunk.decode("utf-8", errors="replace"))[-4096:]
+ challenge = parse_challenge(buffer)
+ if challenge is not None and challenge != previous:
+ on_challenge(challenge)
+ previous = challenge
+
+ async def cleanup() -> None:
+ try:
+ process = await spawning
+ except Exception:
+ return
+ # Cancellation can arrive before normal readers are installed, or cancel
+ # their gather. Pipe transports must finish before process.wait can settle.
+ for reader in readers:
+ reader.cancel()
+ await asyncio.gather(*readers, return_exceptions=True)
+
+ async def discard(stream: asyncio.StreamReader) -> None:
+ while await stream.read(65536):
+ pass
+
+ draining = [
+ asyncio.create_task(discard(stream))
+ for stream in (process.stdout, process.stderr)
+ if stream is not None
+ ]
+ try:
+ if process.returncode is None:
+ with suppress(ProcessLookupError):
+ process.kill()
+ await process.wait()
+ finally:
+ await asyncio.gather(*draining)
+
+ try:
+ process = await asyncio.shield(spawning)
+ if process.stdout is None or process.stderr is None:
+ raise CopilotUnavailable("Copilot login output is unavailable.")
+ readers.extend(
+ (
+ asyncio.create_task(read_output(process.stdout)),
+ asyncio.create_task(read_output(process.stderr)),
+ )
+ )
+ code = await process.wait()
+ await asyncio.gather(*readers)
+ if code != 0:
+ raise CopilotUnavailable(
+ "Copilot sign-in did not complete. Retry Connect or run copilot login --device-code."
+ )
+ finally:
+ await drain_owned(asyncio.create_task(cleanup()))
diff --git a/src/free_claude_code/providers/github_copilot/provider.py b/src/free_claude_code/providers/github_copilot/provider.py
new file mode 100644
index 00000000..d38479c8
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/provider.py
@@ -0,0 +1,362 @@
+"""Copilot subscription models dispatched through FCC's three HTTP egresses."""
+
+import asyncio
+import sys
+from collections.abc import AsyncIterator
+from contextlib import suppress
+
+import httpx
+import httpx2
+from openai import AsyncOpenAI
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.core.openai_responses import OpenAIResponsesRequest
+from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.providers.admission import ProviderAdmissionController
+from free_claude_code.providers.anthropic_messages.transport import (
+ AnthropicMessagesTransport,
+)
+from free_claude_code.providers.base import BaseProvider, ProviderConfig
+from free_claude_code.providers.endpoint import EndpointContext, HttpEndpoint
+from free_claude_code.providers.http import close_provider_stream
+from free_claude_code.providers.openai_chat import OpenAIChatProvider
+from free_claude_code.providers.openai_responses import OpenAIResponsesTransport
+
+from .auth import CopilotAuthManager
+from .lifecycle import drain_owned
+from .request_policy import (
+ PROVIDER_NAME,
+ REPLAY_SCOPE,
+ chat_profile,
+ non_messages_reasoning,
+)
+from .responses_events import CopilotResponsesEvents
+from .types import CopilotEgress, CopilotModel
+
+
+class _BorrowedMessagesPool(httpx.AsyncBaseTransport):
+ def __init__(self, pool: httpx.AsyncBaseTransport) -> None:
+ self._pool = pool
+
+ async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+ return await self._pool.handle_async_request(request)
+
+
+class _MessagesEndpoint:
+ """A fresh snapshot replaces all cookie state for this request's next attempt."""
+
+ def __init__(self, context: EndpointContext, client: httpx.AsyncClient) -> None:
+ self._context = context
+ self._client = client
+
+ async def endpoint(self, *, force_refresh: bool = False) -> HttpEndpoint:
+ snapshot = await self._context.endpoint(force_refresh=force_refresh)
+ self._client.cookies.clear()
+ return snapshot
+
+
+class GitHubCopilotProvider(BaseProvider):
+ """Own generation HTTP resources; borrow the process account for each stream."""
+
+ def __init__(
+ self,
+ config: ProviderConfig,
+ *,
+ auth: CopilotAuthManager,
+ admission: ProviderAdmissionController,
+ messages_transport: httpx.AsyncBaseTransport | None = None,
+ openai_transport: httpx2.AsyncBaseTransport | None = None,
+ ) -> None:
+ super().__init__(config)
+ self._auth = auth
+ self._admission = admission
+ self._messages_pool = messages_transport or httpx.AsyncHTTPTransport(
+ proxy=config.proxy
+ )
+ self._openai_pool = openai_transport or httpx2.AsyncHTTPTransport(
+ proxy=config.proxy
+ )
+ self._client = AsyncOpenAI(
+ api_key=_endpoint_required,
+ base_url=config.base_url,
+ max_retries=0,
+ timeout=httpx2.Timeout(
+ config.http_read_timeout,
+ connect=config.http_connect_timeout,
+ write=config.http_write_timeout,
+ ),
+ )
+ self._responses = OpenAIResponsesTransport(
+ client=self._client,
+ admission=admission,
+ provider_name=PROVIDER_NAME,
+ read_timeout_s=config.http_read_timeout,
+ log_raw_sse_events=config.log_raw_sse_events,
+ endpoint_transport=self._openai_pool,
+ event_adapter_factory=CopilotResponsesEvents,
+ )
+ self._chats: dict[str, tuple[CopilotModel, OpenAIChatProvider]] = {}
+ self._condition = asyncio.Condition()
+ self._active = 0
+ self._closing = False
+ self._closed = False
+ self._cleanup_task: asyncio.Task[None] | None = None
+
+ def _check_model(self, model: str) -> None:
+ if self._closing:
+ raise ExecutionFailure(
+ FailureKind.UNAVAILABLE, 503, "Copilot provider is closing.", False
+ )
+ if not model.strip() or model.strip().casefold() == "auto":
+ raise InvalidRequestError(
+ "Choose a concrete model from the connected Copilot account."
+ )
+
+ def preflight_messages(
+ self,
+ request: MessagesRequest,
+ *,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> None:
+ # Endpoint family and capabilities belong to the current account lease.
+ # Conversion runs after acquisition and before opening the physical stream.
+ self._check_model(request.model)
+
+ def preflight_responses(
+ self,
+ request: OpenAIResponsesRequest,
+ *,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> None:
+ self._check_model(request.model)
+
+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
+ if self._closing:
+ raise ExecutionFailure(
+ FailureKind.UNAVAILABLE, 503, "Copilot provider is closing.", False
+ )
+ return frozenset(
+ model.info for model in (await self._auth.models(refresh=True)).values()
+ )
+
+ def stream_messages(
+ self,
+ request: MessagesRequest,
+ input_tokens: int = 0,
+ *,
+ request_id: str | None = None,
+ response_model: str | None = None,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> AsyncIterator[str]:
+ self.preflight_messages(request, reasoning=reasoning)
+ return self._dispatch(
+ request,
+ input_tokens,
+ request_id,
+ response_model or request.model,
+ reasoning,
+ )
+
+ def stream_responses(
+ self,
+ request: OpenAIResponsesRequest,
+ input_tokens: int = 0,
+ *,
+ request_id: str | None = None,
+ response_model: str | None = None,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> AsyncIterator[str]:
+ self.preflight_responses(request, reasoning=reasoning)
+ return self._dispatch(
+ request,
+ input_tokens,
+ request_id,
+ response_model or request.model,
+ reasoning,
+ )
+
+ def _chat(self, model: CopilotModel) -> OpenAIChatProvider:
+ cached = self._chats.get(model.info.model_id)
+ if cached is None or cached[0] != model:
+ provider = OpenAIChatProvider(
+ self._config,
+ profile=chat_profile(model),
+ admission=self._admission,
+ client=self._client,
+ endpoint_transport=self._openai_pool,
+ )
+ self._chats[model.info.model_id] = (model, provider)
+ return provider
+ return cached[1]
+
+ async def _dispatch(
+ self,
+ request: MessagesRequest | OpenAIResponsesRequest,
+ input_tokens: int,
+ request_id: str | None,
+ response_model: str,
+ reasoning: ReasoningPolicy,
+ ) -> AsyncIterator[str]:
+ async with self._condition:
+ self._check_model(request.model)
+ self._active += 1
+ try:
+ async with self._auth.lease(request.model) as lease:
+ selected: AsyncIterator[str] | None = None
+ http: httpx.AsyncClient | None = None
+ try:
+ if lease.egress is CopilotEgress.MESSAGES:
+ http = httpx.AsyncClient(
+ transport=_BorrowedMessagesPool(self._messages_pool),
+ follow_redirects=False,
+ timeout=httpx.Timeout(
+ self._config.http_read_timeout,
+ connect=self._config.http_connect_timeout,
+ write=self._config.http_write_timeout,
+ ),
+ )
+ native = AnthropicMessagesTransport(
+ client=http,
+ admission=self._admission,
+ provider_name=PROVIDER_NAME,
+ replay_scope=REPLAY_SCOPE,
+ read_timeout_s=self._config.http_read_timeout,
+ capabilities=lease.model.messages,
+ )
+ endpoint = _MessagesEndpoint(lease, http)
+ if isinstance(request, MessagesRequest):
+ selected = native.stream_messages(
+ request,
+ endpoint_context=endpoint,
+ request_id=request_id,
+ response_model=response_model,
+ reasoning=reasoning,
+ )
+ else:
+ selected = native.stream_responses(
+ request,
+ endpoint_context=endpoint,
+ request_id=request_id,
+ response_model=response_model,
+ reasoning=reasoning,
+ )
+ else:
+ resolved = non_messages_reasoning(
+ request, reasoning, lease.model
+ )
+ transport = (
+ self._responses
+ if lease.egress is CopilotEgress.RESPONSES
+ else self._chat(lease.model)
+ )
+ if isinstance(request, MessagesRequest):
+ selected = transport.stream_messages(
+ request,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ response_model=response_model,
+ reasoning=resolved,
+ endpoint_context=lease,
+ )
+ else:
+ selected = transport.stream_responses(
+ request,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ response_model=response_model,
+ reasoning=resolved,
+ endpoint_context=lease,
+ )
+ while True:
+ try:
+ event = await _next_event(selected)
+ except StopAsyncIteration:
+ break
+ yield event
+ finally:
+ await drain_owned(
+ asyncio.create_task(
+ _close_request(
+ selected,
+ http,
+ active_error=sys.exception(),
+ request_id=request_id,
+ )
+ )
+ )
+ finally:
+ async with self._condition:
+ self._active -= 1
+ self._condition.notify_all()
+
+ async def cleanup(self) -> None:
+ if self._closed:
+ return
+ self._closing = True
+ if self._cleanup_task is None or self._cleanup_task.done():
+ self._cleanup_task = asyncio.create_task(self._cleanup())
+ await drain_owned(self._cleanup_task)
+
+ async def _cleanup(self) -> None:
+ async with self._condition:
+ await self._condition.wait_for(lambda: self._active == 0)
+ results = await asyncio.gather(
+ self._client.close(),
+ self._messages_pool.aclose(),
+ self._openai_pool.aclose(),
+ return_exceptions=True,
+ )
+ failures = [result for result in results if isinstance(result, Exception)]
+ if failures:
+ raise ExceptionGroup("Copilot HTTP cleanup failed", failures)
+ self._chats.clear()
+ self._closed = True
+
+
+async def _close_request(
+ stream: AsyncIterator[str] | None,
+ client: httpx.AsyncClient | None,
+ *,
+ active_error: BaseException | None,
+ request_id: str | None,
+) -> None:
+ try:
+ if stream is not None:
+ await close_provider_stream(
+ stream,
+ active_error=active_error,
+ provider_name=PROVIDER_NAME,
+ request_id=request_id,
+ )
+ finally:
+ if client is not None:
+ await client.aclose()
+
+
+async def _endpoint_required() -> str:
+ raise ExecutionFailure(
+ FailureKind.UNAVAILABLE,
+ 503,
+ "Copilot inference requires a current account endpoint.",
+ False,
+ )
+
+
+async def _advance(stream: AsyncIterator[str]) -> str:
+ return await anext(stream)
+
+
+async def _next_event(stream: AsyncIterator[str]) -> str:
+ # Cancel transport work once, then protect its response-close finally blocks
+ # from repeated caller cancellation before releasing the account lease.
+ task = asyncio.create_task(_advance(stream))
+ try:
+ return await asyncio.shield(task)
+ except asyncio.CancelledError:
+ task.cancel()
+ with suppress(Exception, asyncio.CancelledError):
+ await drain_owned(task)
+ raise
diff --git a/src/free_claude_code/providers/github_copilot/request_policy.py b/src/free_claude_code/providers/github_copilot/request_policy.py
new file mode 100644
index 00000000..5bce0c97
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/request_policy.py
@@ -0,0 +1,104 @@
+"""Copilot control encoding from advertised model capabilities."""
+
+from dataclasses import replace
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.core.anthropic import ReasoningReplayMode
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.openai_responses import OpenAIResponsesRequest
+from free_claude_code.core.reasoning import (
+ ReasoningControl,
+ ReasoningEffort,
+ ReasoningPolicy,
+)
+from free_claude_code.providers.openai_chat import (
+ NamedEffortReasoning,
+ OpenAIChatProfile,
+ OpenAIChatRequestPolicy,
+)
+
+from .types import CopilotModel
+
+PROVIDER_NAME = "GITHUB_COPILOT"
+REPLAY_SCOPE = "github_copilot/anthropic_messages"
+
+
+def chat_profile(model: CopilotModel) -> OpenAIChatProfile:
+ advertised = model.supported_efforts or ()
+ return OpenAIChatProfile(
+ OpenAIChatRequestPolicy(
+ provider_name=PROVIDER_NAME,
+ reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
+ reject_extra_body_message="Copilot Chat does not support extra_body overrides.",
+ ),
+ NamedEffortReasoning(
+ efforts=tuple(
+ (effort, effort.value)
+ for effort in ReasoningEffort
+ if effort.value in advertised
+ ),
+ disabled_value="none" if "none" in advertised else None,
+ enabled_value=model.default_effort
+ if model.default_effort in advertised and model.default_effort != "none"
+ else None,
+ ),
+ reasoning_delta_fallback_field="reasoning",
+ )
+
+
+def non_messages_reasoning(
+ request: MessagesRequest | OpenAIResponsesRequest,
+ policy: ReasoningPolicy,
+ model: CopilotModel,
+) -> ReasoningPolicy:
+ """Reject controls these egresses cannot encode before any inference."""
+ raw_effort = (
+ (request.output_config.get("effort") if request.output_config else None)
+ if isinstance(request, MessagesRequest)
+ else (request.reasoning.get("effort") if request.reasoning else None)
+ )
+ if raw_effort is not None and (
+ not isinstance(raw_effort, str)
+ or raw_effort.strip().lower()
+ not in {"none", *(effort.value for effort in ReasoningEffort)}
+ ):
+ raise InvalidRequestError("Unsupported Copilot reasoning effort.")
+ if policy.budget_tokens is not None or (
+ isinstance(request, MessagesRequest)
+ and request.thinking is not None
+ and request.thinking.budget_tokens is not None
+ and policy.control is not ReasoningControl.OFF
+ ):
+ raise InvalidRequestError(
+ "This Copilot endpoint cannot represent an exact thinking token budget."
+ )
+ advertised = model.supported_efforts or ()
+ if policy.control is ReasoningControl.OFF:
+ if "none" not in advertised:
+ raise InvalidRequestError(
+ "This Copilot model does not advertise a way to disable reasoning."
+ )
+ return policy
+ effort = policy.effort
+ if effort is None and policy.control is ReasoningControl.ON:
+ default = model.default_effort
+ if default is None or default == "none" or default not in advertised:
+ raise InvalidRequestError(
+ "This Copilot model does not advertise a default reasoning effort. Choose a supported effort."
+ )
+ try:
+ effort = ReasoningEffort(default)
+ except ValueError:
+ raise InvalidRequestError(
+ "This Copilot model's default reasoning effort is unsupported."
+ ) from None
+ if effort is not None:
+ if (
+ effort.value not in advertised
+ or model.messages.supports_output_effort is False
+ ):
+ raise InvalidRequestError(
+ f"This Copilot model does not advertise support for reasoning effort {effort.value!r}."
+ )
+ return replace(policy, effort=effort)
+ return policy
diff --git a/src/free_claude_code/providers/github_copilot/responses_events.py b/src/free_claude_code/providers/github_copilot/responses_events.py
new file mode 100644
index 00000000..941314d6
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/responses_events.py
@@ -0,0 +1,90 @@
+"""Correlate Copilot's rotating opaque Responses IDs within one attempt."""
+
+from copy import deepcopy
+
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.providers.failure_policy import RetryableProviderProtocolError
+
+
+class CopilotResponsesEvents:
+ """Keep the first opaque ID for each output position, preserving replay data."""
+
+ def __init__(self) -> None:
+ self._response_id: str | None = None
+ self._item_ids: dict[int, str] = {}
+ self._item_metadata: dict[int, tuple[str, str | None, str | None]] = {}
+ self._tool_positions: set[int] = set()
+
+ def __call__(self, event_type: str, payload: JsonObject) -> JsonObject:
+ data = deepcopy(payload)
+ response = data.get("response")
+ if isinstance(response, dict):
+ identifier = response.get("id")
+ if isinstance(identifier, str) and identifier:
+ if self._response_id is None:
+ self._response_id = identifier
+ response["id"] = self._response_id
+ output = response.get("output")
+ if isinstance(output, list):
+ for position, item in enumerate(output):
+ if isinstance(item, dict):
+ self._item(position, item)
+ if "response_id" in data and self._response_id is not None:
+ data["response_id"] = self._response_id
+
+ position = data.get("output_index")
+ valid_position = (
+ isinstance(position, int)
+ and not isinstance(position, bool)
+ and position >= 0
+ )
+ tool_arguments = event_type in {
+ "response.function_call_arguments.delta",
+ "response.function_call_arguments.done",
+ }
+ if tool_arguments and (
+ not valid_position or position not in self._tool_positions
+ ):
+ raise RetryableProviderProtocolError(
+ "Copilot sent tool arguments before identifying their output item."
+ )
+ if valid_position:
+ item = data.get("item")
+ if isinstance(item, dict):
+ self._item(position, item)
+ if ("item_id" in data or tool_arguments) and position in self._item_ids:
+ data["item_id"] = self._item_ids[position]
+ return data
+
+ def _item(self, position: int, item: JsonObject) -> None:
+ identifier = item.get("id")
+ kind = item.get("type")
+ if (
+ not isinstance(identifier, str)
+ or not identifier
+ or not isinstance(kind, str)
+ or not kind
+ ):
+ raise RetryableProviderProtocolError(
+ "Copilot sent incomplete output identity."
+ )
+ call_id = name = None
+ if kind == "function_call":
+ call_id, name = item.get("call_id"), item.get("name")
+ if (
+ not isinstance(call_id, str)
+ or not call_id
+ or not isinstance(name, str)
+ or not name
+ ):
+ raise RetryableProviderProtocolError(
+ "Copilot sent incomplete tool identity."
+ )
+ metadata = (kind, call_id, name)
+ if self._item_metadata.setdefault(position, metadata) != metadata:
+ raise RetryableProviderProtocolError(
+ "Copilot changed the identity of an output item."
+ )
+ item["id"] = self._item_ids.setdefault(position, identifier)
+ if kind == "function_call":
+ self._tool_positions.add(position)
diff --git a/src/free_claude_code/providers/github_copilot/sdk.py b/src/free_claude_code/providers/github_copilot/sdk.py
new file mode 100644
index 00000000..532641e9
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/sdk.py
@@ -0,0 +1,563 @@
+"""Pinned official Copilot SDK boundary; never run SDK agent turns."""
+
+import asyncio
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import uuid
+from collections.abc import Mapping
+from contextlib import suppress
+from pathlib import Path
+from types import MappingProxyType
+from typing import Literal
+from urllib.parse import urlsplit
+
+import httpx
+from copilot import (
+ CapiSessionOptions,
+ CopilotClient,
+ CopilotSession,
+ PermissionRequest,
+ RuntimeConnection,
+)
+from copilot.rpc import (
+ AdaptiveThinkingSupport,
+ Model,
+ ModelPolicyState,
+ ModelsListRequest,
+ PermissionDecisionReject,
+ ProviderEndpoint,
+ ProviderTransport,
+ ProviderType,
+ ProviderWireAPI,
+ SessionProviderGetEndpointRequest,
+)
+from copilot.session import PermissionInvocation
+
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.core.model_capabilities import ModelInputModality
+from free_claude_code.providers.anthropic_messages.request_policy import (
+ MessagesModelCapabilities,
+)
+from free_claude_code.providers.endpoint import HttpEndpoint
+
+from .lifecycle import drain_owned
+from .types import (
+ CopilotEgress,
+ CopilotEndpoint,
+ CopilotIdentity,
+ CopilotModel,
+ CopilotUnavailable,
+)
+
+COPILOT_CLI_VERSION = "1.0.83"
+SDK_RPC_TIMEOUT = 30.0
+_TOKEN_ENV = frozenset(
+ {
+ "COPILOT_GITHUB_TOKEN",
+ "GH_TOKEN",
+ "GITHUB_TOKEN",
+ "GITHUB_COPILOT_API_TOKEN",
+ "COPILOT_API_URL",
+ "COPILOT_SDK_AUTH_TOKEN",
+ "COPILOT_DISABLE_KEYTAR",
+ "COPILOT_OFFLINE",
+ }
+)
+_HEADER_NAME = re.compile(r"[!#$%&'*+.^_`|~0-9A-Za-z-]+")
+
+
+def profile_environment(source: Mapping[str, str] | None = None) -> dict[str, str]:
+ """Keep native profile selection while excluding token and BYOK overrides."""
+ return {
+ key: value
+ for key, value in (os.environ if source is None else source).items()
+ if key.upper() not in _TOKEN_ENV
+ and not key.upper().startswith("COPILOT_PROVIDER_")
+ }
+
+
+async def verified_cli_path(env: Mapping[str, str]) -> str:
+ path = shutil.which("copilot", path=env.get("PATH"))
+ if path is None:
+ raise CopilotUnavailable(
+ f"Install GitHub Copilot CLI {COPILOT_CLI_VERSION}, then connect again."
+ )
+ process = await asyncio.create_subprocess_exec(
+ path,
+ "--version",
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ env=env,
+ creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0,
+ )
+ try:
+ async with asyncio.timeout(15):
+ stdout, _ = await process.communicate()
+ except TimeoutError:
+ raise CopilotUnavailable(
+ "Copilot CLI did not report its version in time. Check the CLI installation and reconnect."
+ ) from None
+ finally:
+ if process.returncode is None:
+ await drain_owned(asyncio.create_task(_close_cli_probe(process)))
+ if (
+ process.returncode != 0
+ or re.match(
+ rf"GitHub Copilot CLI {re.escape(COPILOT_CLI_VERSION)}\.?(?:\r?\n|\Z)",
+ stdout.decode("utf-8", errors="replace"),
+ )
+ is None
+ ):
+ raise CopilotUnavailable(
+ f"FCC requires GitHub Copilot CLI {COPILOT_CLI_VERSION} for its pinned SDK. Install that version and reconnect."
+ )
+ return path
+
+
+async def _close_cli_probe(process: asyncio.subprocess.Process) -> None:
+ with suppress(ProcessLookupError):
+ process.kill()
+ await process.communicate()
+
+
+def _deny_permission(
+ _request: PermissionRequest, _invocation: PermissionInvocation
+) -> PermissionDecisionReject:
+ return PermissionDecisionReject(feedback="FCC owns tool execution.")
+
+
+async def _delete_session_record(
+ client: CopilotClient, session_id: str, *, allow_absent: bool = True
+) -> None:
+ try:
+ async with asyncio.timeout(SDK_RPC_TIMEOUT):
+ await client.delete_session(session_id)
+ except Exception:
+ # Endpoint-only sessions need not have a persisted record. Check this
+ # exact owned UUID; neither error prose nor a failed lookup proves absence.
+ if not allow_absent:
+ raise
+ async with asyncio.timeout(SDK_RPC_TIMEOUT):
+ metadata = await client.get_session_metadata(session_id)
+ if metadata is not None:
+ raise
+
+
+class SdkRuntime:
+ """Own a hidden official runtime with native authentication and inert sessions."""
+
+ def __init__(self) -> None:
+ self._client: CopilotClient | None = None
+ self._directory: tempfile.TemporaryDirectory[str] | None = None
+ self._sessions: list[SdkSession] = []
+ self._pending_session_ids: set[str] = set()
+ self._lock = asyncio.Lock()
+ self._close_task: asyncio.Task[None] | None = None
+ self._closing = False
+ self._stopped = False
+
+ async def start(self) -> None:
+ async with self._lock:
+ if self._closing:
+ raise CopilotUnavailable("Copilot runtime has closed.")
+ if self._client is not None:
+ return
+ env = profile_environment()
+ path = await verified_cli_path(env)
+ env["COPILOT_ALLOW_GET_PROVIDER_ENDPOINT"] = "true"
+ directory = tempfile.TemporaryDirectory(prefix="fcc-copilot-")
+ self._directory = directory
+ try:
+ client = CopilotClient(
+ connection=RuntimeConnection.for_stdio(
+ path=path, args=("--disable-builtin-mcps",)
+ ),
+ env=env,
+ working_directory=directory.name,
+ use_logged_in_user=True,
+ mode="copilot-cli",
+ log_level="error",
+ )
+ self._client = client
+ async with asyncio.timeout(SDK_RPC_TIMEOUT):
+ await client.start()
+ status = await client.get_status()
+ if status.version != COPILOT_CLI_VERSION:
+ raise CopilotUnavailable(
+ "Copilot runtime version changed. Reconnect with the supported CLI version."
+ )
+ except BaseException:
+ self._closing = True
+ await drain_owned(asyncio.create_task(self._close_client()))
+ raise
+
+ def _running(self) -> CopilotClient:
+ if self._client is None:
+ raise CopilotUnavailable("Copilot runtime is not connected.")
+ return self._client
+
+ async def identity(self) -> CopilotIdentity | None:
+ try:
+ async with asyncio.timeout(SDK_RPC_TIMEOUT):
+ status = await self._running().get_auth_status()
+ except Exception:
+ raise CopilotUnavailable(
+ "Could not read Copilot profile status. Reconnect Copilot."
+ ) from None
+ if not status.isAuthenticated:
+ return None
+ if status.authType not in {"user", "gh-cli"}:
+ raise CopilotUnavailable(
+ "Copilot must use an existing GitHub profile. Sign in with copilot login --device-code."
+ )
+ if not status.login or not status.host:
+ raise CopilotUnavailable(
+ "Copilot did not report the selected GitHub profile."
+ )
+ host = urlsplit(
+ status.host if "://" in status.host else f"https://{status.host}"
+ ).hostname
+ if not host:
+ raise CopilotUnavailable("Copilot reported an invalid GitHub profile host.")
+ return CopilotIdentity(host.lower(), status.login)
+
+ async def models(self) -> tuple[CopilotModel, ...]:
+ try:
+ result = await self._running().rpc.models.list(
+ ModelsListRequest(), timeout=SDK_RPC_TIMEOUT
+ )
+ return tuple(
+ _model(model)
+ for model in result.models
+ if model.id.strip()
+ and model.id.strip().casefold() != "auto"
+ and (
+ model.policy is None
+ or model.policy.state is ModelPolicyState.ENABLED
+ )
+ )
+ except Exception:
+ raise CopilotUnavailable(
+ "Could not discover Copilot subscription models. Check the selected account and its model policies."
+ ) from None
+
+ async def session(self, model_id: str) -> SdkSession:
+ client = self._running()
+ directory = self._directory
+ if directory is None:
+ raise CopilotUnavailable("Copilot working directory is unavailable.")
+ session_id = str(uuid.uuid4())
+ config = Path(directory.name) / session_id
+ config.mkdir()
+ self._pending_session_ids.add(session_id)
+ try:
+ async with asyncio.timeout(SDK_RPC_TIMEOUT):
+ session = await client.create_session(
+ session_id=session_id,
+ model=model_id,
+ working_directory=directory.name,
+ config_directory=str(config),
+ available_tools=[],
+ on_permission_request=_deny_permission,
+ enable_config_discovery=False,
+ skip_custom_instructions=True,
+ custom_agents_local_only=True,
+ enable_file_hooks=False,
+ enable_on_demand_instruction_discovery=False,
+ enable_host_git_operations=False,
+ enable_skills=False,
+ included_builtin_skills=[],
+ request_extensions=False,
+ enable_session_store=False,
+ infinite_sessions={"enabled": False},
+ memory={"enabled": False},
+ skip_embedding_retrieval=True,
+ embedding_cache_storage="in-memory",
+ mcp_oauth_token_storage="in-memory",
+ enable_session_telemetry=False,
+ capi=CapiSessionOptions(enable_web_socket_responses=False),
+ )
+ except Exception:
+ raise CopilotUnavailable(
+ "Could not open a Copilot endpoint session. Reconnect Copilot."
+ ) from None
+ owned = SdkSession(client, session, model_id, session_id)
+ self._sessions.append(owned)
+ self._pending_session_ids.discard(session_id)
+ return owned
+
+ async def close(self) -> None:
+ self._closing = True
+ if self._close_task is None or self._close_task.done():
+ self._close_task = asyncio.create_task(self._close())
+ await drain_owned(self._close_task)
+
+ async def _close(self) -> None:
+ async with self._lock:
+ await self._close_client()
+
+ async def _close_client(self) -> None:
+ client = self._client
+ if client is None:
+ if self._directory is not None:
+ self._directory.cleanup()
+ self._directory = None
+ return
+ records_only = self._stopped
+ try:
+ # A prior shutdown can stop the process while record deletion fails.
+ # Retain that ownership and reconnect only to retry our own deletions.
+ if self._stopped:
+ self._stopped = False
+ try:
+ async with asyncio.timeout(SDK_RPC_TIMEOUT):
+ await client.start()
+ except Exception:
+ raise CopilotUnavailable(
+ "Could not reconnect Copilot to remove an FCC session record. Retry disconnect to finish cleanup."
+ ) from None
+ failed_sessions: list[SdkSession] = []
+ for session in self._sessions:
+ try:
+ await session.close(runtime_stopped=records_only)
+ except Exception:
+ failed_sessions.append(session)
+ self._sessions = failed_sessions
+ # A cancelled create RPC can still finish remotely. Do not accept
+ # absence until the process that could create its record has stopped.
+ for session_id in tuple(self._pending_session_ids) if records_only else ():
+ try:
+ await _delete_session_record(client, session_id)
+ self._pending_session_ids.discard(session_id)
+ except Exception:
+ pass
+ finally:
+ # start() may fail after spawning a process. Stop that partial runtime
+ # too, without discarding record IDs still owned by this adapter.
+ try:
+ async with asyncio.timeout(SDK_RPC_TIMEOUT):
+ await client.stop()
+ except Exception:
+ try:
+ async with asyncio.timeout(SDK_RPC_TIMEOUT):
+ await client.force_stop()
+ except Exception:
+ raise CopilotUnavailable(
+ "Could not stop the Copilot runtime. Retry disconnect to finish cleanup."
+ ) from None
+ self._stopped = True
+ if self._pending_session_ids and not records_only:
+ # Reconnect solely to clean known UUIDs after their writer is gone.
+ await self._close_client()
+ return
+ if self._sessions or self._pending_session_ids:
+ raise CopilotUnavailable(
+ "Copilot stopped, but an FCC session record could not be removed. Retry disconnect to finish cleanup."
+ )
+ self._client = None
+ if self._directory is not None:
+ self._directory.cleanup()
+ self._directory = None
+
+
+class SdkSession:
+ def __init__(
+ self,
+ client: CopilotClient,
+ session: CopilotSession,
+ model_id: str,
+ session_id: str,
+ ) -> None:
+ self._client = client
+ self._session = session
+ self._model_id = model_id
+ self._session_id = session_id
+ self._closed = False
+ self._disconnected = False
+ self._close_task: asyncio.Task[None] | None = None
+
+ async def endpoint(self) -> CopilotEndpoint:
+ if self._closed:
+ raise CopilotUnavailable("Copilot endpoint session is closed.")
+ try:
+ endpoint = await self._session.rpc.provider.get_endpoint(
+ SessionProviderGetEndpointRequest(model_id=self._model_id),
+ timeout=SDK_RPC_TIMEOUT,
+ )
+ return _endpoint(endpoint, self._model_id)
+ except CopilotUnavailable:
+ raise
+ except Exception:
+ raise CopilotUnavailable(
+ "Could not resolve this model's Copilot endpoint. Refresh models or reconnect Copilot."
+ ) from None
+
+ async def close(self, *, runtime_stopped: bool = False) -> None:
+ if runtime_stopped:
+ # Only SdkRuntime, after stopping the owning process, supplies this.
+ self._disconnected = True
+ if self._closed:
+ return
+ if self._close_task is None or self._close_task.done():
+ self._close_task = asyncio.create_task(self._close())
+ await drain_owned(self._close_task)
+
+ async def _close(self) -> None:
+ if not self._disconnected:
+ try:
+ async with asyncio.timeout(SDK_RPC_TIMEOUT):
+ await self._session.disconnect()
+ self._disconnected = True
+ except Exception:
+ # Deletion and runtime stop also release server-side ownership.
+ pass
+ await _delete_session_record(
+ self._client, self._session_id, allow_absent=self._disconnected
+ )
+ self._closed = True
+
+
+def _model(model: Model) -> CopilotModel:
+ limits = model.capabilities.limits
+ supports = model.capabilities.supports
+ adaptive: Literal["unsupported", "optional", "required"] | None = None
+ if supports is not None and supports.adaptive_thinking is not None:
+ modes: dict[
+ AdaptiveThinkingSupport, Literal["unsupported", "optional", "required"]
+ ] = {
+ AdaptiveThinkingSupport.UNSUPPORTED: "unsupported",
+ AdaptiveThinkingSupport.OPTIONAL: "optional",
+ AdaptiveThinkingSupport.REQUIRED: "required",
+ }
+ adaptive = modes[supports.adaptive_thinking]
+ vision = supports.vision if supports is not None else None
+ effort_support = supports.reasoning_effort if supports is not None else None
+ efforts = (
+ tuple(model.supported_reasoning_efforts)
+ if model.supported_reasoning_efforts is not None
+ else None
+ )
+ output = limits.max_output_tokens if limits is not None else None
+ context = limits.max_context_window_tokens if limits is not None else None
+ info = ProviderModelInfo(
+ model_id=model.id,
+ supports_thinking=True
+ if effort_support is True or adaptive in {"optional", "required"}
+ else None,
+ input_modalities=frozenset({ModelInputModality.TEXT, ModelInputModality.IMAGE})
+ if vision is True
+ else frozenset({ModelInputModality.TEXT})
+ if vision is False
+ else None,
+ context_window_tokens=context if context is not None and context > 0 else None,
+ max_output_tokens=output if output is not None and output > 0 else None,
+ )
+ return CopilotModel(
+ info,
+ MessagesModelCapabilities(
+ max_output_tokens=info.max_output_tokens,
+ adaptive_thinking=adaptive,
+ supports_output_effort=effort_support,
+ supported_efforts=efforts,
+ supports_vision=vision,
+ ),
+ efforts,
+ model.default_reasoning_effort,
+ )
+
+
+def _endpoint(endpoint: ProviderEndpoint, model_id: str) -> CopilotEndpoint:
+ if endpoint.transport not in {None, ProviderTransport.HTTP}:
+ raise CopilotUnavailable(
+ "This Copilot model requires an unsupported upstream transport."
+ )
+ if endpoint.type is ProviderType.ANTHROPIC and endpoint.wire_api is None:
+ egress = CopilotEgress.MESSAGES
+ elif endpoint.type is ProviderType.OPENAI:
+ egress = (
+ CopilotEgress.RESPONSES
+ if endpoint.wire_api is ProviderWireAPI.RESPONSES
+ else CopilotEgress.CHAT
+ )
+ else:
+ raise CopilotUnavailable(
+ "This Copilot model requires an unsupported provider endpoint."
+ )
+ try:
+ url = urlsplit(endpoint.base_url)
+ valid_url = (
+ url.scheme == "https"
+ and bool(url.hostname)
+ and url.username is None
+ and url.password is None
+ and not url.query
+ and not url.fragment
+ and not any(
+ character.isspace() or ord(character) < 32
+ for character in endpoint.base_url
+ )
+ and (url.port is None or url.port > 0)
+ )
+ except ValueError:
+ valid_url = False
+ if not valid_url:
+ raise CopilotUnavailable("Copilot returned an invalid HTTPS endpoint.")
+ headers = httpx.Headers(encoding="ascii")
+ for key, value in endpoint.headers.items():
+ if _HEADER_NAME.fullmatch(key) is None or any(
+ character in value for character in "\r\n\0"
+ ):
+ raise CopilotUnavailable("Copilot returned invalid endpoint headers.")
+ try:
+ headers[key] = value
+ except UnicodeError, ValueError:
+ raise CopilotUnavailable(
+ "Copilot returned invalid endpoint headers."
+ ) from None
+ expires = None
+ token = endpoint.session_token
+ if token is not None:
+ if (
+ token.model not in {None, model_id}
+ or not token.token
+ or _HEADER_NAME.fullmatch(token.header) is None
+ or any(character in token.token for character in "\r\n\0")
+ ):
+ raise CopilotUnavailable(
+ "Copilot returned an invalid or differently bound session token."
+ )
+ try:
+ headers[token.header] = token.token
+ except UnicodeError, ValueError:
+ raise CopilotUnavailable(
+ "Copilot returned an invalid session token."
+ ) from None
+ if token.expires_at is not None:
+ if token.expires_at.tzinfo is None:
+ raise CopilotUnavailable(
+ "Copilot returned a session expiry without a time zone."
+ )
+ expires = token.expires_at.timestamp()
+ if endpoint.api_key is not None:
+ if not endpoint.api_key or any(
+ character in endpoint.api_key for character in "\r\n\0"
+ ):
+ raise CopilotUnavailable("Copilot returned an invalid endpoint credential.")
+ try:
+ endpoint.api_key.encode("ascii")
+ except UnicodeError:
+ raise CopilotUnavailable(
+ "Copilot returned an invalid endpoint credential."
+ ) from None
+ return CopilotEndpoint(
+ egress,
+ HttpEndpoint(
+ endpoint.base_url.rstrip("/"),
+ MappingProxyType(dict(headers.items())),
+ endpoint.api_key,
+ ),
+ expires,
+ )
diff --git a/src/free_claude_code/providers/github_copilot/types.py b/src/free_claude_code/providers/github_copilot/types.py
new file mode 100644
index 00000000..09a3bab1
--- /dev/null
+++ b/src/free_claude_code/providers/github_copilot/types.py
@@ -0,0 +1,67 @@
+"""Immutable Copilot metadata and the narrow runtime boundary."""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Protocol
+
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.providers.anthropic_messages.request_policy import (
+ MessagesModelCapabilities,
+)
+from free_claude_code.providers.endpoint import HttpEndpoint
+
+
+class CopilotUnavailable(RuntimeError):
+ """A safe, actionable message about Copilot runtime availability."""
+
+
+class CopilotAuthenticationRequired(CopilotUnavailable):
+ """The selected native profile needs interactive authentication."""
+
+
+class CopilotEgress(StrEnum):
+ MESSAGES = "messages"
+ RESPONSES = "responses"
+ CHAT = "chat"
+
+
+@dataclass(frozen=True, slots=True)
+class CopilotIdentity:
+ host: str
+ login: str
+
+ @property
+ def display(self) -> str:
+ return (
+ f"@{self.login}"
+ if self.host == "github.com"
+ else f"@{self.login} ({self.host})"
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class CopilotModel:
+ info: ProviderModelInfo
+ messages: MessagesModelCapabilities
+ supported_efforts: tuple[str, ...] | None = None
+ default_effort: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CopilotEndpoint:
+ egress: CopilotEgress
+ http: HttpEndpoint = field(repr=False)
+ expires_at: float | None = None
+
+
+class CopilotSession(Protocol):
+ async def endpoint(self) -> CopilotEndpoint: ...
+ async def close(self) -> None: ...
+
+
+class CopilotRuntime(Protocol):
+ async def start(self) -> None: ...
+ async def identity(self) -> CopilotIdentity | None: ...
+ async def models(self) -> tuple[CopilotModel, ...]: ...
+ async def session(self, model_id: str) -> CopilotSession: ...
+ async def close(self) -> None: ...
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index 8b52892e..175d1be5 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -56,6 +56,7 @@ from free_claude_code.providers.admission import (
ProviderOperationKind,
)
from free_claude_code.providers.base import BaseProvider, ProviderConfig
+from free_claude_code.providers.endpoint import EndpointContext, RequestEndpoint
from free_claude_code.providers.failure_policy import (
RetryableToolProtocolError,
classify_provider_failure,
@@ -494,11 +495,14 @@ class OpenAIChatProvider(BaseProvider):
admission: ProviderAdmissionController,
default_headers: Mapping[str, str] | None = None,
api_key_provider: OpenAIAsyncCredentialProvider | None = None,
+ client: AsyncOpenAI | None = None,
+ endpoint_transport: httpx2.AsyncBaseTransport | None = None,
):
super().__init__(config)
self._profile = profile
+ self._endpoint_transport = endpoint_transport
self._provider_name = profile.provider_name
- if config.api_key is None and api_key_provider is None:
+ if client is None and config.api_key is None and api_key_provider is None:
raise ValueError(
f"{profile.provider_name} requires an API key or credential provider"
)
@@ -515,12 +519,13 @@ class OpenAIChatProvider(BaseProvider):
write=config.http_write_timeout,
)
http_client = None
- if config.proxy:
+ if client is None and config.proxy:
http_client = DefaultAsyncHttpx2Client(
proxy=config.proxy,
timeout=timeout,
)
- self._client = AsyncOpenAI(
+ self._owns_client = client is None
+ self._client = client or AsyncOpenAI(
api_key=api_key_provider or self._api_key,
base_url=self._base_url,
max_retries=0,
@@ -532,7 +537,7 @@ class OpenAIChatProvider(BaseProvider):
async def cleanup(self) -> None:
"""Release HTTP client resources."""
client = getattr(self, "_client", None)
- if client is not None:
+ if self._owns_client and client is not None:
await client.close()
async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
@@ -778,6 +783,7 @@ class OpenAIChatProvider(BaseProvider):
operation_kind: ProviderOperationKind,
*,
used_retry_kinds: set[str] | None = None,
+ endpoint: RequestEndpoint | None = None,
) -> tuple[Any, dict, ProviderAttempt]:
"""Create a streaming chat completion with bounded request fallbacks."""
body = self._apply_learned_output_cap(body)
@@ -790,7 +796,15 @@ class OpenAIChatProvider(BaseProvider):
retain_attempt = False
try:
create_body = self._prepare_create_body(body)
- stream = await self._client.chat.completions.create(
+ client = (
+ await endpoint.openai_client(self._client)
+ if endpoint is not None
+ else self._client
+ )
+ if endpoint is not None:
+ create_body = create_body.copy()
+ create_body["extra_headers"] = endpoint.openai_headers()
+ stream = await client.chat.completions.create(
**create_body,
stream=True,
)
@@ -800,6 +814,10 @@ class OpenAIChatProvider(BaseProvider):
except asyncio.CancelledError:
raise
except Exception as error:
+ if endpoint is not None and await endpoint.retry_authentication(
+ error, attempt, execution
+ ):
+ continue
retry_body = self._next_create_retry_body(error, body, used_retry_kinds)
if retry_body is not None:
correction = await attempt.correct(error)
@@ -900,6 +918,7 @@ class OpenAIChatProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ endpoint_context: EndpointContext | None = None,
) -> AsyncIterator[str]:
"""Stream response in Anthropic SSE format."""
body = self._build_request_body(request, reasoning=reasoning)
@@ -923,6 +942,7 @@ class OpenAIChatProvider(BaseProvider):
request.model if response_model is None else response_model
),
reasoning=reasoning,
+ endpoint_context=endpoint_context,
)
return runner.run()
@@ -934,6 +954,7 @@ class OpenAIChatProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ endpoint_context: EndpointContext | None = None,
) -> AsyncIterator[str]:
"""Stream a Chat upstream directly as OpenAI Responses SSE."""
translated = self._build_responses_request_body(request, reasoning=reasoning)
@@ -957,6 +978,7 @@ class OpenAIChatProvider(BaseProvider):
request_id=request_id,
response_model=public_model,
reasoning=reasoning,
+ endpoint_context=endpoint_context,
)
return runner.run()
@@ -977,6 +999,7 @@ class _OpenAIChatStreamRunner:
request_id: str | None,
response_model: str,
reasoning: ReasoningPolicy,
+ endpoint_context: EndpointContext | None = None,
) -> None:
self._provider = provider
self._body = body
@@ -989,6 +1012,11 @@ class _OpenAIChatStreamRunner:
self._response_model = response_model
self._reasoning = reasoning
self._terminal_failure: ExecutionFailure | None = None
+ self._endpoint = (
+ RequestEndpoint(endpoint_context, provider._endpoint_transport)
+ if endpoint_context is not None
+ else None
+ )
async def run(self) -> AsyncIterator[str]:
"""Convert the upstream OpenAI-chat stream into Anthropic SSE."""
@@ -998,6 +1026,8 @@ class _OpenAIChatStreamRunner:
provider_stream = self._run_execution(execution)
try:
async for event in provider_stream:
+ if self._endpoint is not None:
+ self._endpoint.commit()
yield event
except asyncio.CancelledError:
raise
@@ -1010,8 +1040,14 @@ class _OpenAIChatStreamRunner:
else:
execution.fail(self._terminal_failure)
finally:
- await maybe_await_aclose(provider_stream)
- execution.abandon()
+ try:
+ await maybe_await_aclose(provider_stream)
+ finally:
+ try:
+ if self._endpoint is not None:
+ await self._endpoint.aclose()
+ finally:
+ execution.abandon()
async def _run_execution(
self,
@@ -1052,6 +1088,7 @@ class _OpenAIChatStreamRunner:
execution,
ProviderOperationKind.GENERATION,
used_retry_kinds=used_retry_kinds,
+ endpoint=self._endpoint,
)
scope = ProviderAttemptScope(
attempt,
@@ -1169,6 +1206,15 @@ class _OpenAIChatStreamRunner:
req_tag: str,
) -> _OpenAIChatFailureResolution:
"""Resolve one failed generation attempt without owning retry policy."""
+ if (
+ scope is not None
+ and self._endpoint is not None
+ and await self._endpoint.retry_authentication(
+ error, scope.attempt, execution
+ )
+ ):
+ recovery.discard()
+ return _OpenAIChatFailureResolution(outcome=_OpenAIChatFailureOutcome.RETRY)
attempt_failure = None
if scope is not None and not scope.attempt.accepted:
attempt_failure = await scope.attempt.fail(
@@ -1324,6 +1370,7 @@ class _OpenAIChatStreamRunner:
execution,
operation_kind,
used_retry_kinds=used_retry_kinds,
+ endpoint=self._endpoint,
)
scope = ProviderAttemptScope(
attempt,
diff --git a/src/free_claude_code/providers/openai_responses/transport.py b/src/free_claude_code/providers/openai_responses/transport.py
index f96037a3..8668cd4c 100644
--- a/src/free_claude_code/providers/openai_responses/transport.py
+++ b/src/free_claude_code/providers/openai_responses/transport.py
@@ -3,9 +3,10 @@
import asyncio
import sys
import uuid
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Callable
from typing import cast
+import httpx2
from openai import AsyncOpenAI, AsyncStream
from openai.types.responses import ResponseInputParam, ResponseStreamEvent
from openai.types.responses.response_create_params import ResponseCreateParamsStreaming
@@ -32,12 +33,14 @@ from free_claude_code.providers.admission import (
ProviderExecution,
ProviderOperationKind,
)
+from free_claude_code.providers.endpoint import EndpointContext, RequestEndpoint
from free_claude_code.providers.failure_policy import (
RetryableProviderProtocolError,
classify_provider_failure,
context_window_exceeded_provider_failure,
is_context_window_error_code,
is_retryable_stream_error,
+ provider_authentication_status,
reports_context_window_incomplete,
)
from free_claude_code.providers.http import ProviderAttemptScope, maybe_await_aclose
@@ -53,6 +56,8 @@ from .presentation import (
ResponsesPresenterFactory,
)
+type ResponsesEventAdapter = Callable[[str, JsonObject], JsonObject]
+
class _TruncatedResponsesStream(RetryableProviderProtocolError):
"""A Responses stream ended without a terminal lifecycle event."""
@@ -85,8 +90,12 @@ class OpenAIResponsesTransport:
provider_name: str,
read_timeout_s: float,
log_raw_sse_events: bool,
+ endpoint_transport: httpx2.AsyncBaseTransport | None = None,
+ event_adapter_factory: Callable[[], ResponsesEventAdapter] | None = None,
) -> None:
self._client = client
+ self._endpoint_transport = endpoint_transport
+ self._event_adapter_factory = event_adapter_factory
self._admission = admission
self._provider_name = provider_name
self._read_timeout_s = read_timeout_s
@@ -108,12 +117,14 @@ class OpenAIResponsesTransport:
request_id: str | None,
response_model: str,
reasoning: ReasoningPolicy,
+ endpoint_context: EndpointContext | None = None,
) -> AsyncIterator[str]:
body = self._build_messages_body(request, reasoning=reasoning)
tool_names = OpenAIToolNameCodec.from_request(request)
message_id = f"msg_{uuid.uuid4()}"
return self._run_stream(
body,
+ endpoint_context=endpoint_context,
request_id=request_id,
response_model=response_model,
presenter_factory=lambda: MessagesResponsesPresenter(
@@ -143,11 +154,13 @@ class OpenAIResponsesTransport:
request_id: str | None,
response_model: str,
reasoning: ReasoningPolicy,
+ endpoint_context: EndpointContext | None = None,
) -> AsyncIterator[str]:
del input_tokens
body = self._build_native_body(request, reasoning=reasoning)
return self._run_stream(
body,
+ endpoint_context=endpoint_context,
request_id=request_id,
response_model=response_model,
presenter_factory=lambda: NativeResponsesPresenter(
@@ -195,9 +208,15 @@ class OpenAIResponsesTransport:
request_id: str | None,
response_model: str,
presenter_factory: ResponsesPresenterFactory,
+ endpoint_context: EndpointContext | None = None,
) -> AsyncIterator[str]:
execution = self._admission.start_execution(request_id=request_id)
outcome = ResponsesExecutionOutcome()
+ endpoint = (
+ RequestEndpoint(endpoint_context, self._endpoint_transport)
+ if endpoint_context is not None
+ else None
+ )
provider_stream = self._run_execution(
body,
request_id=request_id,
@@ -205,9 +224,12 @@ class OpenAIResponsesTransport:
presenter_factory=presenter_factory,
execution=execution,
outcome=outcome,
+ endpoint=endpoint,
)
try:
async for event in provider_stream:
+ if endpoint is not None:
+ endpoint.commit()
yield event
except asyncio.CancelledError:
raise
@@ -220,8 +242,14 @@ class OpenAIResponsesTransport:
else:
execution.fail(outcome.failure)
finally:
- await maybe_await_aclose(provider_stream)
- execution.abandon()
+ try:
+ await maybe_await_aclose(provider_stream)
+ finally:
+ try:
+ if endpoint is not None:
+ await endpoint.aclose()
+ finally:
+ execution.abandon()
async def _run_execution(
self,
@@ -232,6 +260,7 @@ class OpenAIResponsesTransport:
presenter_factory: ResponsesPresenterFactory,
execution: ProviderExecution,
outcome: ResponsesExecutionOutcome,
+ endpoint: RequestEndpoint | None = None,
) -> AsyncIterator[str]:
recovery = RecoveryController()
trace_event(
@@ -250,6 +279,11 @@ class OpenAIResponsesTransport:
presenter = presenter_factory()
start_events = tuple(presenter.start())
presenter_started = False
+ adapt_event = (
+ self._event_adapter_factory()
+ if self._event_adapter_factory is not None
+ else None
+ )
scope: ProviderAttemptScope | None = None
stream_opened = False
@@ -260,7 +294,7 @@ class OpenAIResponsesTransport:
provider_name=self._provider_name,
request_id=request_id,
)
- sdk_stream = await self._create_sdk_stream(body)
+ sdk_stream = await self._create_sdk_stream(body, endpoint=endpoint)
stream = scope.retain(_ClosableResponsesStream(sdk_stream))
stream_opened = True
@@ -281,15 +315,28 @@ class OpenAIResponsesTransport:
"error",
"response.error",
}:
- raise responses_stream_failure_from_event(
+ stream_failure = responses_stream_failure_from_event(
upstream_event.type,
payload,
)
+ if adapt_event is not None:
+ try:
+ stream_failure.payload = adapt_event(
+ upstream_event.type, payload
+ )
+ except RetryableProviderProtocolError:
+ # Preserve the upstream failure classification.
+ # Synthesize the terminal event if partial output
+ # cannot retain a consistent public identity.
+ stream_failure.payload = None
+ raise stream_failure
if reports_context_window_incomplete(
upstream_event.type,
payload,
):
raise context_window_exceeded_provider_failure()
+ if adapt_event is not None:
+ payload = adapt_event(upstream_event.type, payload)
for event in presenter.feed(upstream_event.type, payload):
for held in recovery.push(event):
yield held
@@ -314,6 +361,15 @@ class OpenAIResponsesTransport:
raise
except Exception as raw_error:
error = _effective_error(raw_error)
+ if (
+ scope is not None
+ and endpoint is not None
+ and await endpoint.retry_authentication(
+ error, scope.attempt, execution
+ )
+ ):
+ recovery.discard()
+ continue
attempt_failure = None
if scope is not None and not scope.attempt.accepted:
attempt_failure = await scope.attempt.fail(error)
@@ -385,6 +441,8 @@ class OpenAIResponsesTransport:
async def _create_sdk_stream(
self,
body: JsonObject,
+ *,
+ endpoint: RequestEndpoint | None = None,
) -> AsyncStream[ResponseStreamEvent]:
model = body.get("model")
if not isinstance(model, str) or not model:
@@ -395,12 +453,18 @@ class OpenAIResponsesTransport:
for key, value in body.items()
if key not in {"model", "input", "stream", "store"}
}
- return await self._client.responses.create(
+ client = (
+ await endpoint.openai_client(self._client)
+ if endpoint is not None
+ else self._client
+ )
+ return await client.responses.create(
model=model,
input=input_value,
stream=True,
store=False,
extra_body=extra_body or None,
+ extra_headers=endpoint.openai_headers() if endpoint is not None else None,
)
@@ -413,6 +477,16 @@ def _effective_error(error: Exception) -> Exception:
)
if is_context_window_error_code(error.code):
return context_window_exceeded_provider_failure()
+ auth_status = provider_authentication_status(error)
+ if auth_status is not None:
+ return ExecutionFailure(
+ FailureKind.AUTHENTICATION
+ if auth_status == 401
+ else FailureKind.PERMISSION,
+ auth_status,
+ message,
+ False,
+ )
code = (error.code or "").lower()
if "rate" in code or "429" in code:
return ExecutionFailure(FailureKind.RATE_LIMIT, 429, message, True)
diff --git a/src/free_claude_code/providers/opencode/provider.py b/src/free_claude_code/providers/opencode/provider.py
index e263bb61..0b39638f 100644
--- a/src/free_claude_code/providers/opencode/provider.py
+++ b/src/free_claude_code/providers/opencode/provider.py
@@ -14,6 +14,7 @@ from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.endpoint import EndpointContext
from free_claude_code.providers.http import close_provider_stream
from free_claude_code.providers.openai_chat import (
NO_REASONING,
@@ -162,6 +163,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ endpoint_context: EndpointContext | None = None,
) -> AsyncIterator[str]:
return self._dispatch_stream(
request,
@@ -169,6 +171,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id=request_id,
response_model=response_model or request.model,
reasoning=reasoning,
+ endpoint_context=endpoint_context,
)
async def _dispatch_stream(
@@ -179,6 +182,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id: str | None,
response_model: str,
reasoning: ReasoningPolicy,
+ endpoint_context: EndpointContext | None = None,
) -> AsyncIterator[str]:
snapshot = await self._catalog.snapshot(request_id=request_id)
route = self._require_route(snapshot, request.model)
@@ -193,6 +197,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id=request_id,
response_model=response_model,
reasoning=reasoning,
+ endpoint_context=endpoint_context,
)
else:
super().preflight_messages(routed, reasoning=reasoning)
@@ -202,6 +207,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id=request_id,
response_model=response_model,
reasoning=reasoning,
+ endpoint_context=endpoint_context,
)
async for event in selected_stream:
yield event
@@ -222,6 +228,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id: str | None = None,
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ endpoint_context: EndpointContext | None = None,
) -> AsyncIterator[str]:
return self._dispatch_responses_stream(
request,
@@ -229,6 +236,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id=request_id,
response_model=response_model or request.model,
reasoning=reasoning,
+ endpoint_context=endpoint_context,
)
async def _dispatch_responses_stream(
@@ -239,6 +247,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id: str | None,
response_model: str,
reasoning: ReasoningPolicy,
+ endpoint_context: EndpointContext | None = None,
) -> AsyncIterator[str]:
snapshot = await self._catalog.snapshot(request_id=request_id)
route = self._require_route(snapshot, request.model)
@@ -253,6 +262,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id=request_id,
response_model=response_model,
reasoning=reasoning,
+ endpoint_context=endpoint_context,
)
else:
super().preflight_responses(routed, reasoning=reasoning)
@@ -262,6 +272,7 @@ class OpenCodeProvider(OpenAIChatProvider):
request_id=request_id,
response_model=response_model,
reasoning=reasoning,
+ endpoint_context=endpoint_context,
)
async for event in selected_stream:
yield event
diff --git a/src/free_claude_code/providers/runtime/factory.py b/src/free_claude_code/providers/runtime/factory.py
index 079854f1..e8527981 100644
--- a/src/free_claude_code/providers/runtime/factory.py
+++ b/src/free_claude_code/providers/runtime/factory.py
@@ -169,7 +169,7 @@ _SPECIAL_PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
"opencode_zen": _create_opencode_zen,
"opencode_go": _create_opencode_go,
}
-_INJECTED_PROVIDER_IDS = {"openai"}
+_INJECTED_PROVIDER_IDS = {"openai", "github_copilot"}
def _required_setting(settings: Settings, attr_name: str) -> str:
diff --git a/src/free_claude_code/runtime/bootstrap.py b/src/free_claude_code/runtime/bootstrap.py
index 4a55b722..ed970b6a 100644
--- a/src/free_claude_code/runtime/bootstrap.py
+++ b/src/free_claude_code/runtime/bootstrap.py
@@ -18,6 +18,8 @@ from free_claude_code.messaging.transcription import TranscriptionService
from free_claude_code.messaging.voice import Transcriber
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import BaseProvider, ProviderConfig
+from free_claude_code.providers.github_copilot.auth import CopilotAuthManager
+from free_claude_code.providers.github_copilot.provider import GitHubCopilotProvider
from free_claude_code.providers.nvidia_nim.voice import NvidiaNimTranscriber
from free_claude_code.providers.openai_codex import (
OpenAIAuthManager,
@@ -45,10 +47,15 @@ def build_asgi_app(
verbose_third_party=settings.log_raw_api_payloads,
)
openai_auth = OpenAIAuthManager(proxy=settings.openai_proxy)
+ copilot_auth = CopilotAuthManager()
+ copilot_factory = partial(_create_copilot_provider, auth=copilot_auth)
openai_factory = partial(_create_openai_provider, auth=openai_auth)
provider_constructor = partial(
create_provider,
- injected_factories={"openai": openai_factory},
+ injected_factories={
+ "openai": openai_factory,
+ "github_copilot": copilot_factory,
+ },
)
runtime_factory = partial(
ProviderRuntime,
@@ -57,7 +64,10 @@ def build_asgi_app(
provider_manager = ProviderRuntimeManager(
settings,
runtime_factory=runtime_factory,
- connected_provider_ids=openai_auth.connected_provider_ids,
+ connected_provider_ids=lambda: (
+ *openai_auth.connected_provider_ids(),
+ *copilot_auth.connected_provider_ids(),
+ ),
model_catalog_publisher=CodexModelCatalogPublisher(),
)
chat_service = ChatService(
@@ -69,7 +79,7 @@ def build_asgi_app(
chat_service=chat_service,
transcriber=_create_transcriber(settings),
restart_callback=restart_callback,
- connected_accounts={"openai": openai_auth},
+ connected_accounts={"openai": openai_auth, "github_copilot": copilot_auth},
)
services = ApiServices(
requests=provider_manager,
@@ -90,6 +100,16 @@ def _create_openai_provider(
return OpenAICodexProvider(config, auth=auth, admission=admission)
+def _create_copilot_provider(
+ config: ProviderConfig,
+ _settings: Settings,
+ admission: ProviderAdmissionController,
+ *,
+ auth: CopilotAuthManager,
+) -> BaseProvider:
+ return GitHubCopilotProvider(config, auth=auth, admission=admission)
+
+
def _create_transcriber(settings: Settings) -> Transcriber | None:
if not settings.voice_note_enabled:
return None
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index 7c18c9fc..5477de11 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -1,4 +1,5 @@
import asyncio
+from dataclasses import replace
from pathlib import Path
from unittest.mock import AsyncMock, patch
@@ -334,32 +335,20 @@ def test_admin_api_fetches_bypass_browser_cache():
assert 'cache: "no-store"' in script
-def test_admin_connected_account_login_preopens_sign_in_window():
- script = Path("src/free_claude_code/api/admin_static/admin.js").read_text(
- encoding="utf-8"
- )
-
- assert 'window.open("about:blank", "_blank")' in script
- assert "popup.location.replace(target)" in script
- assert "if (popup) popup.close()" in script
- assert '"Reconnect"' in script
- assert '"Copy code"' in script
- assert "Restart your agent to refresh its model picker." in script
- assert 'window.confirm("Disconnect this ChatGPT account from FCC?")' in script
-
-
class _FakeConnectedAccount:
- def __init__(self) -> None:
+ def __init__(self, provider_id: str = "openai") -> None:
+ self.provider_id = provider_id
self.connected = False
self.revision = 0
self.cancelled = False
+ self.started_modes: list[ConnectedAccountLoginMode] = []
def is_connected(self) -> bool:
return self.connected
def status(self) -> ConnectedAccountStatus:
- return ConnectedAccountStatus(
- provider_id="openai",
+ status = ConnectedAccountStatus(
+ provider_id=self.provider_id,
state=(
ConnectedAccountState.CONNECTED
if self.connected
@@ -367,20 +356,37 @@ class _FakeConnectedAccount:
),
connected=self.connected,
revision=self.revision,
- email="[email protected]" if self.connected else None,
)
+ if self.provider_id == "github_copilot":
+ return replace(
+ status,
+ display_identity="octocat" if self.connected else None,
+ supported_login_modes=(ConnectedAccountLoginMode.DEVICE,),
+ default_login_mode=ConnectedAccountLoginMode.DEVICE,
+ )
+ return replace(status, email="[email protected]" if self.connected else None)
async def start_login(
self, mode: ConnectedAccountLoginMode
) -> ConnectedAccountStatus:
- return ConnectedAccountStatus(
- provider_id="openai",
+ self.started_modes.append(mode)
+ return replace(
+ self.status(),
state=ConnectedAccountState.CONNECTING,
connected=False,
- revision=self.revision,
attempt_id="login_safe",
mode=mode,
- authorization_url="https://auth.openai.com/safe",
+ authorization_url=(
+ "https://auth.openai.com/safe"
+ if mode == ConnectedAccountLoginMode.BROWSER
+ else None
+ ),
+ verification_url=(
+ "https://github.com/login/device"
+ if mode == ConnectedAccountLoginMode.DEVICE
+ else None
+ ),
+ user_code="ABCD-1234" if mode == ConnectedAccountLoginMode.DEVICE else None,
)
async def cancel_login(self) -> ConnectedAccountStatus:
@@ -423,6 +429,8 @@ def test_admin_connected_account_routes_are_safe_loopback_only_and_uncached(
"attempt_id": "login_safe",
"mode": "browser",
"authorization_url": "https://auth.openai.com/safe",
+ "supported_login_modes": ["browser", "device"],
+ "default_login_mode": "browser",
}
assert "token" not in login_response.text.lower()
assert cancel_response.status_code == 200
@@ -431,6 +439,105 @@ def test_admin_connected_account_routes_are_safe_loopback_only_and_uncached(
assert remote.get("/admin/api/providers/openai/auth").status_code == 403
+ ("provider_id", "default_mode"),
+ [("openai", "browser"), ("github_copilot", "device")],
+)
[email protected]("payload", [{}, {"mode": None}])
+def test_admin_login_uses_the_provider_default(
+ monkeypatch,
+ tmp_path,
+ provider_id,
+ default_mode,
+ payload,
+):
+ _set_home(monkeypatch, tmp_path)
+ account = _FakeConnectedAccount(provider_id)
+ client = _local_client(
+ create_test_app(providers={}, connected_accounts={provider_id: account})
+ )
+
+ response = client.post(
+ f"/admin/api/providers/{provider_id}/auth/login", json=payload
+ )
+
+ assert response.status_code == 200
+ assert response.headers["cache-control"] == "no-store"
+ assert response.json()["mode"] == default_mode
+ assert account.started_modes == [ConnectedAccountLoginMode(default_mode)]
+ if default_mode == "device":
+ assert response.json()["user_code"] == "ABCD-1234"
+ assert response.json()["verification_url"] == "https://github.com/login/device"
+ assert "authorization_url" not in response.json()
+
+
[email protected]("mode", ["browser", "unrecognized"])
+def test_admin_rejects_unsupported_login_modes_before_starting(
+ monkeypatch, tmp_path, mode
+):
+ _set_home(monkeypatch, tmp_path)
+ account = _FakeConnectedAccount("github_copilot")
+ client = _local_client(
+ create_test_app(providers={}, connected_accounts={"github_copilot": account})
+ )
+
+ response = client.post(
+ "/admin/api/providers/github_copilot/auth/login", json={"mode": mode}
+ )
+
+ assert response.status_code == 422
+ assert response.headers["cache-control"] == "no-store"
+ assert account.started_modes == []
+
+
+def test_admin_connected_account_identity_modes_and_disconnect_are_independent(
+ monkeypatch, tmp_path
+):
+ _set_home(monkeypatch, tmp_path)
+ openai = _FakeConnectedAccount()
+ copilot = _FakeConnectedAccount("github_copilot")
+ openai.connected = copilot.connected = True
+ client = _local_client(
+ create_test_app(
+ providers={},
+ connected_accounts={"openai": openai, "github_copilot": copilot},
+ )
+ )
+
+ openai_status = client.get("/admin/api/providers/openai/auth").json()
+ copilot_status = client.get("/admin/api/providers/github_copilot/auth").json()
+ assert openai_status["email"] == "[email protected]"
+ assert openai_status["supported_login_modes"] == ["browser", "device"]
+ assert copilot_status["display_identity"] == "octocat"
+ assert "email" not in copilot_status
+ assert copilot_status["supported_login_modes"] == ["device"]
+ assert copilot_status["default_login_mode"] == "device"
+ assert "token" not in str(copilot_status).lower()
+
+ cancelled = client.post("/admin/api/providers/github_copilot/auth/cancel")
+ assert cancelled.status_code == 200
+ assert copilot.cancelled is True
+ assert openai.cancelled is False
+ disconnected = client.delete("/admin/api/providers/github_copilot/auth")
+ assert disconnected.status_code == 200
+ assert disconnected.json()["connected"] is False
+ assert disconnected.json()["supported_login_modes"] == ["device"]
+ assert client.get("/admin/api/providers/openai/auth").json()["connected"] is True
+
+
+def test_admin_openai_keeps_explicit_device_login(monkeypatch, tmp_path):
+ _set_home(monkeypatch, tmp_path)
+ account = _FakeConnectedAccount()
+ client = _local_client(create_test_app(connected_accounts={"openai": account}))
+
+ response = client.post(
+ "/admin/api/providers/openai/auth/login", json={"mode": "device"}
+ )
+
+ assert response.status_code == 200
+ assert account.started_modes == [ConnectedAccountLoginMode.DEVICE]
+
+
def test_admin_rejects_auth_routes_for_non_connected_provider(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
diff --git a/tests/application/test_connected_accounts.py b/tests/application/test_connected_accounts.py
new file mode 100644
index 00000000..b52cfb47
--- /dev/null
+++ b/tests/application/test_connected_accounts.py
@@ -0,0 +1,46 @@
+"""Safe connected-account capabilities preserve provider identity semantics."""
+
+from free_claude_code.application.connected_accounts import (
+ ConnectedAccountLoginMode,
+ ConnectedAccountState,
+ ConnectedAccountStatus,
+)
+
+
+def test_existing_account_defaults_remain_browser_and_device() -> None:
+ status = ConnectedAccountStatus(
+ provider_id="openai",
+ state=ConnectedAccountState.CONNECTED,
+ connected=True,
+ revision=1,
+ )
+
+ payload = status.as_dict()
+
+ assert payload["email"] == "[email protected]"
+ assert payload["supported_login_modes"] == ["browser", "device"]
+ assert payload["default_login_mode"] == "browser"
+ assert "display_identity" not in payload
+
+
+def test_display_identity_does_not_impersonate_an_email_address() -> None:
+ status = ConnectedAccountStatus(
+ provider_id="github_copilot",
+ state=ConnectedAccountState.CONNECTED,
+ connected=True,
+ revision=2,
+ display_identity="octocat",
+ supported_login_modes=(ConnectedAccountLoginMode.DEVICE,),
+ default_login_mode=ConnectedAccountLoginMode.DEVICE,
+ )
+
+ assert status.as_dict() == {
+ "provider_id": "github_copilot",
+ "state": "connected",
+ "connected": True,
+ "revision": 2,
+ "display_identity": "octocat",
+ "supported_login_modes": ["device"],
+ "default_login_mode": "device",
+ }
diff --git a/tests/config/test_provider_catalog.py b/tests/config/test_provider_catalog.py
index 301fd22e..f3ec5857 100644
--- a/tests/config/test_provider_catalog.py
+++ b/tests/config/test_provider_catalog.py
@@ -73,3 +73,11 @@ def test_openai_is_a_connected_account_without_api_key_configuration() -> None:
assert descriptor.credential_env is None
assert descriptor.configuration_attrs() == ()
assert descriptor.default_base_url == "https://chatgpt.com/backend-api/codex"
+
+
+def test_copilot_is_connected_without_credential_configuration() -> None:
+ descriptor = PROVIDER_CATALOG["github_copilot"]
+ assert descriptor.auth_kind is ProviderAuthKind.CONNECTED_ACCOUNT
+ assert descriptor.credential_env is None
+ assert descriptor.configuration_attrs() == ()
+ assert descriptor.default_base_url == "https://api.githubcopilot.com"
diff --git a/tests/contracts/test_feature_manifest.py b/tests/contracts/test_feature_manifest.py
index 892323e3..e03f49f5 100644
--- a/tests/contracts/test_feature_manifest.py
+++ b/tests/contracts/test_feature_manifest.py
@@ -7,6 +7,7 @@ from free_claude_code.providers.base import BaseProvider
from free_claude_code.providers.cloudflare import CloudflareProvider
from free_claude_code.providers.deepseek import DeepSeekProvider
from free_claude_code.providers.gemini import GeminiProvider
+from free_claude_code.providers.github_copilot.provider import GitHubCopilotProvider
from free_claude_code.providers.groq import GroqProvider
from free_claude_code.providers.kilo import KiloProvider
from free_claude_code.providers.lmstudio import LMStudioProvider
@@ -65,6 +66,7 @@ def test_product_coverage_is_not_satisfied_by_prereq_probes() -> None:
def test_provider_and_platform_registries_include_builtins() -> None:
specialized_provider_classes = {
"openai": OpenAICodexProvider,
+ "github_copilot": GitHubCopilotProvider,
"opencode_zen": OpenCodeProvider,
"opencode_go": OpenCodeProvider,
"nvidia_nim": NvidiaNimProvider,
diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.py
index 5c6c29f5..0ce01642 100644
--- a/tests/contracts/test_provider_catalog_order.py
+++ b/tests/contracts/test_provider_catalog_order.py
@@ -11,6 +11,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
"groq",
"cline_pass",
"openai",
+ "github_copilot",
"xai",
"qwencloud",
"qwencloud_coding",
diff --git a/tests/core/anthropic/test_native_messages.py b/tests/core/anthropic/test_native_messages.py
new file mode 100644
index 00000000..3ef883ee
--- /dev/null
+++ b/tests/core/anthropic/test_native_messages.py
@@ -0,0 +1,270 @@
+"""Native Messages preserves wire content while applying FCC-owned controls."""
+
+import json
+from collections.abc import AsyncIterator
+
+import pytest
+
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.native import (
+ NativeMessagesError,
+ NativeMessagesOptions,
+ build_native_messages_request,
+)
+from free_claude_code.core.anthropic.sse_aggregation import (
+ aggregate_anthropic_sse_to_message,
+)
+from free_claude_code.core.json_types import JsonObject
+
+
+def test_native_body_rejects_nonfinite_json_before_http_serialization() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "public",
+ "messages": [{"role": "user", "content": "hi"}],
+ "extra_body": {"extension": float("nan")},
+ }
+ )
+ with pytest.raises(NativeMessagesError, match="finite JSON"):
+ build_native_messages_request(
+ request, options=NativeMessagesOptions("native", 4096)
+ )
+
+
+def test_native_body_preserves_blocks_and_merges_leading_system_in_order() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "public",
+ "original_model": "private-routing",
+ "max_tokens": 100,
+ "stream": False,
+ "system": "top",
+ "messages": [
+ {"role": "system", "content": "first"},
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "second",
+ "cache_control": {"type": "ephemeral"},
+ }
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "", "signature": "signed"},
+ {
+ "type": "tool_use",
+ "id": "call-a",
+ "name": "lookup",
+ "input": {"x": 1},
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "call-a",
+ "content": [
+ {
+ "type": "image",
+ "source": {
+ "type": "url",
+ "url": "https://example.org/image.png",
+ },
+ }
+ ],
+ "is_error": False,
+ }
+ ],
+ },
+ ],
+ "thinking": {"enabled": True, "type": "adaptive", "display": "omitted"},
+ "output_config": {
+ "effort": "high",
+ "format": {"type": "json_schema", "schema": {"type": "object"}},
+ },
+ "extra_body": {"service_tier": "auto"},
+ "betas": ["feature-2026-09-04", "feature-2026-09-04"],
+ }
+ )
+ before = request.model_dump()
+ prepared = build_native_messages_request(
+ request,
+ options=NativeMessagesOptions("upstream", 8192, {"type": "disabled"}),
+ )
+ assert prepared.betas == ("feature-2026-09-04",)
+ assert prepared.body["model"] == "upstream"
+ assert prepared.body["stream"] is True
+ assert prepared.body["max_tokens"] == 8192
+ assert prepared.body["thinking"] == {"type": "disabled"}
+ assert prepared.body["output_config"] == {
+ "format": {"type": "json_schema", "schema": {"type": "object"}}
+ }
+ assert prepared.body["service_tier"] == "auto"
+ assert prepared.body["system"] == [
+ {"type": "text", "text": "top"},
+ {"type": "text", "text": "first"},
+ {"type": "text", "text": "second", "cache_control": {"type": "ephemeral"}},
+ ]
+ assert prepared.body["messages"] == [
+ message.model_dump(exclude_none=True) for message in request.messages[2:]
+ ]
+ assert (
+ not {"betas", "extra_body", "original_model", "resolved_provider_model"}
+ & prepared.body.keys()
+ )
+ assert request.model_dump() == before
+
+
+ "extra",
+ [
+ {"model": "other"},
+ {"thinking": {"type": "enabled"}},
+ {"Authorization": "secret"},
+ {"headers": {"x-test": "x"}},
+ {"max_tokens": 42},
+ {"temperature": 0.9},
+ ],
+)
+def test_extra_body_cannot_override_owned_or_explicit_fields(extra: JsonObject) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "m",
+ "messages": [{"role": "user", "content": "hi"}],
+ "temperature": 0.3,
+ "extra_body": extra,
+ }
+ )
+ with pytest.raises(NativeMessagesError, match="cannot override"):
+ build_native_messages_request(request, options=NativeMessagesOptions("m", 1024))
+
+
+def test_late_system_and_unsigned_compatibility_reasoning_rejected() -> None:
+ for messages in (
+ [{"role": "user", "content": "hi"}, {"role": "system", "content": "late"}],
+ [{"role": "assistant", "content": "hi", "reasoning_content": "unsigned"}],
+ ):
+ request = MessagesRequest.model_validate({"model": "m", "messages": messages})
+ with pytest.raises(NativeMessagesError):
+ build_native_messages_request(
+ request, options=NativeMessagesOptions("m", 1024)
+ )
+
+
+def test_forced_tool_with_manual_thinking_rejected() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "m",
+ "messages": [{"role": "user", "content": "hi"}],
+ "tool_choice": {"type": "any"},
+ }
+ )
+ with pytest.raises(NativeMessagesError, match="force a tool"):
+ build_native_messages_request(
+ request,
+ options=NativeMessagesOptions(
+ "m", 4096, {"type": "enabled", "budget_tokens": 1024}
+ ),
+ )
+
+
+def test_beta_header_injection_rejected() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "m",
+ "messages": [{"role": "user", "content": "hi"}],
+ "betas": ["bad\r\nAuthorization: secret"],
+ }
+ )
+ with pytest.raises(NativeMessagesError, match="header tokens"):
+ build_native_messages_request(request, options=NativeMessagesOptions("m", 1024))
+
+
+async def test_nonstreaming_aggregation_appends_split_signatures() -> None:
+ events: list[JsonObject] = [
+ {"type": "message_start", "message": {"id": "m", "model": "x", "usage": {}}},
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "thinking", "thinking": "", "signature": "start"},
+ },
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "signature_delta", "signature": "-middle"},
+ },
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "signature_delta", "signature": "-end"},
+ },
+ {"type": "content_block_stop", "index": 0},
+ {
+ "type": "message_delta",
+ "delta": {"stop_reason": "end_turn"},
+ "usage": {"output_tokens": 10},
+ },
+ {"type": "message_stop"},
+ ]
+
+ async def stream() -> AsyncIterator[str]:
+ for event in events:
+ frame = f"event: {event['type']}\ndata: {json.dumps(event)}\n\n"
+ for pos in range(0, len(frame), 7):
+ yield frame[pos : pos + 7]
+
+ body, error, complete = await aggregate_anthropic_sse_to_message(stream())
+ assert complete and error is None
+ assert body["content"] == [
+ {"type": "thinking", "thinking": "", "signature": "start-middle-end"}
+ ]
+
+
+def test_native_top_level_cache_and_tier_survive_and_cannot_be_shadowed() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "m",
+ "messages": [{"role": "user", "content": "hi"}],
+ "cache_control": {"type": "ephemeral"},
+ "service_tier": "standard_only",
+ }
+ )
+ body = build_native_messages_request(
+ request, options=NativeMessagesOptions("m", 1024)
+ ).body
+ assert body["cache_control"] == {"type": "ephemeral"}
+ assert body["service_tier"] == "standard_only"
+ request.extra_body = {"service_tier": "auto"}
+ with pytest.raises(NativeMessagesError, match="cannot override"):
+ build_native_messages_request(request, options=NativeMessagesOptions("m", 1024))
+
+
+def test_unknown_native_field_is_rejected_instead_of_lost() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "m",
+ "messages": [{"role": "user", "content": "hi"}],
+ "future_control": {"mode": "required"},
+ }
+ )
+ with pytest.raises(NativeMessagesError, match="future_control"):
+ build_native_messages_request(request, options=NativeMessagesOptions("m", 1024))
+
+
[email protected]("value", [True, False])
+def test_messages_wire_limit_rejects_boolean_json(value: object) -> None:
+ with pytest.raises(ValueError, match="boolean"):
+ MessagesRequest.model_validate(
+ {
+ "model": "m",
+ "messages": [{"role": "user", "content": "hi"}],
+ "max_tokens": value,
+ }
+ )
diff --git a/tests/core/anthropic/test_native_messages_stream.py b/tests/core/anthropic/test_native_messages_stream.py
new file mode 100644
index 00000000..32971c43
--- /dev/null
+++ b/tests/core/anthropic/test_native_messages_stream.py
@@ -0,0 +1,226 @@
+"""Native relay validation never rewrites identities or completes a truncated stream."""
+
+from collections.abc import AsyncIterator
+from typing import cast
+
+import pytest
+
+from free_claude_code.core.anthropic.native import NativeMessagesError
+from free_claude_code.core.anthropic.native_stream import (
+ NativeMessagesRelay,
+ NativeMessagesStreamState,
+)
+from free_claude_code.core.anthropic.sse_aggregation import (
+ aggregate_anthropic_sse_to_message,
+)
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_lines
+from free_claude_code.core.json_types import JsonObject, JsonValue
+
+_START: JsonObject = {
+ "type": "message_start",
+ "message": {
+ "id": "upstream-id",
+ "type": "message",
+ "model": "upstream",
+ "role": "assistant",
+ "content": [],
+ "usage": {"input_tokens": 3, "output_tokens": 0},
+ "native_extension": "kept",
+ },
+}
+
+
[email protected]("initial", [None, []])
+async def test_native_citations_survive_block_completion_and_fragmented_aggregation(
+ initial: JsonValue,
+) -> None:
+ citation: JsonObject = {
+ "type": "char_location",
+ "cited_text": "source",
+ "document_index": 0,
+ "start_char_index": 0,
+ "end_char_index": 6,
+ "document_title": "doc",
+ }
+ events: list[JsonObject] = [
+ _START,
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "text", "text": "answer", "citations": initial},
+ },
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "citations_delta", "citation": citation},
+ },
+ {"type": "content_block_stop", "index": 0},
+ {
+ "type": "message_delta",
+ "delta": {"stop_reason": "end_turn"},
+ "usage": {"output_tokens": 2},
+ },
+ {"type": "message_stop"},
+ ]
+ state = NativeMessagesStreamState()
+ completed = None
+ for event in events:
+ block = state.accept(cast(str, event["type"]), event)
+ if block is not None:
+ completed = block
+ assert completed is not None and completed["citations"] == [citation]
+ relay = NativeMessagesRelay(public_model="public")
+
+ async def stream() -> AsyncIterator[str]:
+ for event in events:
+ chunk = relay.feed(cast(str, event["type"]), event)
+ for start in range(0, len(chunk), 3):
+ yield chunk[start : start + 3]
+
+ message, error, complete = await aggregate_anthropic_sse_to_message(stream())
+ assert complete and error is None
+ assert message["content"][0]["citations"] == [citation]
+
+
+def test_relay_preserves_native_identity_and_extensions_without_mutating_input() -> (
+ None
+):
+ relay = NativeMessagesRelay(public_model="public")
+ result = parse_sse_lines(relay.feed("message_start", _START).splitlines())[0].data
+ assert result["message"]["model"] == "public"
+ assert result["message"]["id"] == "upstream-id"
+ assert result["message"]["native_extension"] == "kept"
+ assert cast(JsonObject, _START["message"])["model"] == "upstream"
+ block: JsonObject = {
+ "type": "content_block_start",
+ "index": 5,
+ "content_block": {"type": "text", "text": "hello", "citations": []},
+ }
+ assert (
+ parse_sse_lines(relay.feed("content_block_start", block).splitlines())[0].data
+ == block
+ )
+ assert not relay.completed
+
+
+async def test_fragmented_native_relay_preserves_nonstreaming_thinking_and_usage() -> (
+ None
+):
+ relay = NativeMessagesRelay(public_model="public")
+ events: list[JsonObject] = [
+ _START,
+ {
+ "type": "content_block_start",
+ "index": 2,
+ "content_block": {"type": "thinking", "thinking": ""},
+ },
+ {
+ "type": "content_block_delta",
+ "index": 2,
+ "delta": {"type": "signature_delta", "signature": "sig-"},
+ },
+ {
+ "type": "content_block_delta",
+ "index": 2,
+ "delta": {"type": "signature_delta", "signature": "end"},
+ },
+ {"type": "content_block_stop", "index": 2},
+ {
+ "type": "message_delta",
+ "delta": {"stop_reason": "end_turn"},
+ "usage": {"output_tokens": 8},
+ },
+ {"type": "message_stop"},
+ ]
+
+ async def stream() -> AsyncIterator[str]:
+ for event in events:
+ chunk = relay.feed(cast(str, event["type"]), event)
+ for start in range(0, len(chunk), 5):
+ yield chunk[start : start + 5]
+
+ message, error, complete = await aggregate_anthropic_sse_to_message(stream())
+ assert relay.completed and complete and error is None
+ assert message["id"] == "upstream-id" and message["model"] == "public"
+ assert message["content"] == [
+ {"type": "thinking", "thinking": "", "signature": "sig-end"}
+ ]
+ assert message["usage"] == {"input_tokens": 3, "output_tokens": 8}
+
+
+ "event",
+ [
+ _START,
+ {"type": "message_stop"},
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "text_delta", "text": "orphan"},
+ },
+ {
+ "type": "content_block_start",
+ "index": True,
+ "content_block": {"type": "text", "text": ""},
+ },
+ {"type": "message_delta", "delta": {"stop_reason": "unknown"}},
+ ],
+)
+def test_invalid_lifecycles_are_not_reported_as_success(event: JsonObject) -> None:
+ relay = NativeMessagesRelay(public_model="public")
+ relay.feed("message_start", _START)
+ with pytest.raises(NativeMessagesError):
+ relay.feed(cast(str, event["type"]), event)
+ assert not relay.completed
+
+
+def test_reused_block_indexes_and_events_after_terminal_are_rejected() -> None:
+ relay = NativeMessagesRelay(public_model="public")
+ relay.feed("message_start", _START)
+ start: JsonObject = {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "text", "text": ""},
+ }
+ relay.feed("content_block_start", start)
+ relay.feed("content_block_stop", {"type": "content_block_stop", "index": 0})
+ with pytest.raises(NativeMessagesError, match="Duplicate"):
+ relay.feed("content_block_start", start)
+ relay.feed(
+ "message_delta", {"type": "message_delta", "delta": {"stop_reason": "end_turn"}}
+ )
+ relay.feed("message_stop", {"type": "message_stop"})
+ with pytest.raises(NativeMessagesError, match="after message_stop"):
+ relay.feed("message_stop", {"type": "message_stop"})
+
+
[email protected]("partial", ['{"x":', "[]", '{"x":NaN}'])
+def test_invalid_json_tools_never_complete(partial: str) -> None:
+ relay = NativeMessagesRelay(public_model="public")
+ relay.feed("message_start", _START)
+ relay.feed(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {
+ "type": "tool_use",
+ "id": "c",
+ "name": "lookup",
+ "input": {},
+ },
+ },
+ )
+ relay.feed(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "input_json_delta", "partial_json": partial},
+ },
+ )
+ with pytest.raises(NativeMessagesError, match="arguments"):
+ relay.feed("content_block_stop", {"type": "content_block_stop", "index": 0})
+ assert not relay.completed
diff --git a/tests/core/anthropic/test_native_sse_framing.py b/tests/core/anthropic/test_native_sse_framing.py
new file mode 100644
index 00000000..62a95e05
--- /dev/null
+++ b/tests/core/anthropic/test_native_sse_framing.py
@@ -0,0 +1,25 @@
+"""Only SSE line terminators split frames; Unicode text stays verbatim."""
+
+import json
+
+import pytest
+
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.anthropic.streaming.decoder import AnthropicSSEDecoder
+
+
[email protected]("newline", ["\r", "\n", "\r\n"])
[email protected]("width", range(1, 8))
+def test_incremental_sse_terminators_preserve_unicode_text(
+ newline: str, width: int
+) -> None:
+ payload = {"type": "text_delta", "text": "left\u2028middle\u2029right\u0085end"}
+ frame = f"event: content_block_delta{newline}data: {json.dumps(payload, ensure_ascii=False)}{newline}{newline}"
+ raw = frame * 2
+ assert [event.data for event in parse_sse_text(raw)] == [payload, payload]
+ decoder = AnthropicSSEDecoder()
+ events = []
+ for start in range(0, len(raw), width):
+ events.extend(decoder.feed(raw[start : start + width]))
+ assert [event.data for event in events] == [payload, payload]
+ assert decoder.finish() == ()
diff --git a/tests/core/openai_responses/test_messages_request.py b/tests/core/openai_responses/test_messages_request.py
new file mode 100644
index 00000000..abbe8d9c
--- /dev/null
+++ b/tests/core/openai_responses/test_messages_request.py
@@ -0,0 +1,468 @@
+"""Direct Responses-to-Messages contracts for caller-owned transcripts."""
+
+from collections.abc import Mapping
+
+import pytest
+
+from free_claude_code.core.anthropic.native import NativeMessagesOptions
+from free_claude_code.core.json_types import JsonObject, JsonValue
+from free_claude_code.core.openai_responses import (
+ OpenAIResponsesRequest,
+ ResponsesConversionError,
+ ResponsesMessagesRequest,
+ build_responses_messages_request,
+)
+from free_claude_code.core.openai_responses.reasoning_replay import (
+ MessagesReplayOrigin,
+ encode_messages_reasoning,
+)
+
+_SCOPE = "github_copilot/anthropic_messages"
+_FUNCTION: JsonObject = {
+ "type": "function",
+ "name": "lookup",
+ "description": "Find a record.",
+ "parameters": {
+ "type": "object",
+ "properties": {"query": {"type": "string"}},
+ "required": ["query"],
+ },
+ "strict": True,
+}
+
+
[email protected]("arguments", ['{"x":NaN}', '{"x":"\\ud800"}'])
+def test_historical_arguments_must_be_serializable_native_json(arguments: str) -> None:
+ with pytest.raises(ResponsesConversionError, match="finite JSON"):
+ _build(
+ {
+ "input": [
+ {
+ "type": "function_call",
+ "call_id": "c",
+ "name": "lookup",
+ "arguments": arguments,
+ },
+ {"type": "function_call_output", "call_id": "c", "output": "ok"},
+ ]
+ }
+ )
+
+
[email protected]("custom", [False, True])
[email protected]("output", ["", [], [{"type": "input_text", "text": ""}]])
+def test_empty_tool_results_omit_native_content(
+ custom: bool, output: JsonValue
+) -> None:
+ call: JsonObject = {
+ "type": "custom_tool_call" if custom else "function_call",
+ "call_id": "c",
+ "name": "lookup",
+ }
+ call["input" if custom else "arguments"] = "command" if custom else "{}"
+ built = _build(
+ {
+ "input": [
+ call,
+ {
+ "type": "custom_tool_call_output"
+ if custom
+ else "function_call_output",
+ "call_id": "c",
+ "output": output,
+ },
+ ]
+ }
+ )
+ messages = built.body["messages"]
+ assert isinstance(messages, list)
+ assert messages[-1] == {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": "c"}],
+ }
+
+
+def _build(
+ payload: JsonObject, *, thinking: JsonObject | None = None
+) -> ResponsesMessagesRequest:
+ return build_responses_messages_request(
+ OpenAIResponsesRequest.model_validate(
+ {"model": "public", "input": "hi", **payload}
+ ),
+ options=NativeMessagesOptions("concrete", 4096, thinking),
+ replay_scope=_SCOPE,
+ )
+
+
+def test_text_controls_and_stateless_history_policy() -> None:
+ built = _build(
+ {
+ "input": "hello",
+ "instructions": "Be concise.",
+ "stream": False,
+ "store": True,
+ "previous_response_id": "old",
+ "max_output_tokens": 99999,
+ "temperature": 0.2,
+ "top_p": 0.8,
+ "metadata": {"user_id": "person"},
+ }
+ )
+ assert built.body == {
+ "model": "concrete",
+ "max_tokens": 4096,
+ "stream": True,
+ "system": [{"type": "text", "text": "Be concise."}],
+ "messages": [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],
+ "temperature": 0.2,
+ "top_p": 0.8,
+ "metadata": {"user_id": "person"},
+ }
+
+
+def test_parallel_function_and_custom_roundtrip_preserves_replay_order_and_images() -> (
+ None
+):
+ native_thinking: JsonObject = {
+ "type": "thinking",
+ "thinking": "authoritative",
+ "signature": "opaque",
+ "extension": {"record": 1},
+ }
+ carrier = encode_messages_reasoning(
+ native_thinking, origin=MessagesReplayOrigin(_SCOPE, "source")
+ )
+ tools: list[JsonValue] = [
+ {
+ "type": "namespace",
+ "name": "records",
+ "description": "Record operations.",
+ "tools": [_FUNCTION],
+ },
+ {"type": "custom", "name": "shell.exec", "format": {"type": "text"}},
+ ]
+ built = _build(
+ {
+ "tools": tools,
+ "input": [
+ {"role": "system", "content": "first"},
+ {
+ "role": "developer",
+ "content": [{"type": "input_text", "text": "second"}],
+ },
+ {
+ "role": "user",
+ "content": [
+ {"type": "input_text", "text": "Find it"},
+ {
+ "type": "input_image",
+ "image_url": "data:image/png;base64,aGk=",
+ "detail": "auto",
+ },
+ ],
+ },
+ {
+ "type": "reasoning",
+ "encrypted_content": carrier,
+ "content": [
+ {
+ "type": "reasoning_text",
+ "text": "display copy must not duplicate",
+ }
+ ],
+ },
+ {
+ "type": "function_call",
+ "call_id": "lookup-id",
+ "namespace": "records",
+ "name": "lookup",
+ "arguments": '{"query":"x"}',
+ },
+ {
+ "type": "custom_tool_call",
+ "call_id": "custom-id",
+ "name": "shell.exec",
+ "input": "pwd",
+ },
+ {
+ "type": "function_call_output",
+ "call_id": "lookup-id",
+ "output": [
+ {"type": "input_text", "text": "found"},
+ {
+ "type": "input_image",
+ "image_url": "https://example.org/result.png",
+ },
+ ],
+ },
+ {
+ "type": "custom_tool_call_output",
+ "call_id": "custom-id",
+ "output": "done",
+ },
+ {"role": "user", "content": "Summarize."},
+ ],
+ },
+ thinking={"type": "disabled"},
+ )
+ assert built.body["system"] == [
+ {"type": "text", "text": "first"},
+ {"type": "text", "text": "second"},
+ ]
+ messages = built.body["messages"]
+ assert isinstance(messages, list) and len(messages) == 3
+ assistant = messages[1]
+ assert isinstance(assistant, Mapping)
+ blocks = assistant["content"]
+ assert isinstance(blocks, list)
+ assert blocks[0] == native_thinking
+ assert blocks[1] == {
+ "type": "tool_use",
+ "id": "lookup-id",
+ "name": "records__lookup",
+ "input": {"query": "x"},
+ }
+ custom = blocks[2]
+ assert isinstance(custom, Mapping) and isinstance(custom["name"], str)
+ assert custom["input"] == {"input": "pwd"}
+ assert built.tool_identities[custom["name"]].name == "shell.exec"
+ assert built.tool_identities[custom["name"]].kind == "custom"
+ last = messages[2]
+ assert isinstance(last, Mapping)
+ assert last["content"] == [
+ {
+ "type": "tool_result",
+ "tool_use_id": "lookup-id",
+ "content": [
+ {"type": "text", "text": "found"},
+ {
+ "type": "image",
+ "source": {"type": "url", "url": "https://example.org/result.png"},
+ },
+ ],
+ },
+ {
+ "type": "tool_result",
+ "tool_use_id": "custom-id",
+ "content": [{"type": "text", "text": "done"}],
+ },
+ {"type": "text", "text": "Summarize."},
+ ]
+ declarations = built.body["tools"]
+ assert isinstance(declarations, list)
+ assert isinstance(declarations[0], Mapping) and declarations[0]["strict"] is True
+ assert "Record operations." in str(declarations[0]["description"])
+ assert "Find a record." in str(declarations[0]["description"])
+
+
+ ("choice", "parallel", "expected"),
+ [
+ ("none", False, {"type": "none"}),
+ ("auto", False, {"type": "auto", "disable_parallel_tool_use": True}),
+ ("required", True, {"type": "any"}),
+ (
+ {"type": "function", "name": "lookup"},
+ False,
+ {"type": "tool", "name": "lookup", "disable_parallel_tool_use": True},
+ ),
+ ],
+)
+def test_tool_choices_preserve_declarations(
+ choice: JsonValue, parallel: bool, expected: JsonObject
+) -> None:
+ built = _build(
+ {"tools": [_FUNCTION], "tool_choice": choice, "parallel_tool_calls": parallel}
+ )
+ assert built.body["tool_choice"] == expected
+ assert built.body["tools"]
+
+
+def test_named_choice_requires_declaration_and_manual_thinking_rejects_forcing() -> (
+ None
+):
+ with pytest.raises(ResponsesConversionError, match="declared"):
+ _build(
+ {"tools": [_FUNCTION], "tool_choice": {"type": "function", "name": "other"}}
+ )
+ with pytest.raises(ResponsesConversionError, match="force a tool"):
+ _build(
+ {"tools": [_FUNCTION], "tool_choice": "required"},
+ thinking={"type": "enabled", "budget_tokens": 1024},
+ )
+
+
+ "tools",
+ [
+ [_FUNCTION, _FUNCTION],
+ [_FUNCTION, {"type": "custom", "name": "lookup"}],
+ [
+ {"type": "function", "name": "records__lookup"},
+ {"type": "namespace", "name": "records", "tools": [_FUNCTION]},
+ ],
+ [
+ {"type": "namespace", "name": "record.ops", "tools": [_FUNCTION]},
+ {"type": "namespace", "name": "record_ops", "tools": [_FUNCTION]},
+ ],
+ ],
+)
+def test_duplicate_or_flattened_tool_identity_collisions_rejected(
+ tools: list[JsonValue],
+) -> None:
+ with pytest.raises(ResponsesConversionError, match=r"Duplicate|collide"):
+ _build({"tools": tools})
+
+
+_CALL: JsonObject = {
+ "type": "function_call",
+ "call_id": "c",
+ "name": "lookup",
+ "arguments": '{"query":"x"}',
+}
+_RESULT: JsonObject = {"type": "function_call_output", "call_id": "c", "output": "ok"}
+
+
+ "items",
+ [
+ [_CALL],
+ [_RESULT],
+ [_CALL, _CALL, _RESULT],
+ [_CALL, _RESULT, _RESULT],
+ [_CALL, {"role": "user", "content": "intervening"}, _RESULT],
+ [_CALL, {**_RESULT, "type": "custom_tool_call_output"}],
+ [{**_CALL, "call_id": ""}, _RESULT],
+ [{**_CALL, "arguments": "[]"}, _RESULT],
+ [{**_CALL, "arguments": ""}, _RESULT],
+ [{**_CALL, "arguments": None}, _RESULT],
+ [
+ _CALL,
+ {
+ "type": "function_call",
+ "call_id": "d",
+ "name": "lookup",
+ "arguments": "{}",
+ },
+ _RESULT,
+ {"role": "assistant", "content": "too early"},
+ ],
+ ],
+)
+def test_malformed_tool_history_is_rejected_before_inference(
+ items: list[JsonValue],
+) -> None:
+ with pytest.raises(ResponsesConversionError):
+ _build({"tools": [_FUNCTION], "input": items})
+
+
+ "payload",
+ [
+ {
+ "input": [
+ {"role": "user", "content": "hi"},
+ {"role": "system", "content": "late"},
+ ]
+ },
+ {"input": [{"type": "item_reference", "id": "remote"}]},
+ {
+ "input": [
+ {"role": "user", "content": [{"type": "input_file", "file_id": "file"}]}
+ ]
+ },
+ {"input": [{"type": "input_image", "file_id": "file"}]},
+ {"input": [{"type": "input_image", "image_url": "file:///private.png"}]},
+ {"input": [{"type": "input_image", "image_url": "data:image/png;base64,!!!"}]},
+ {
+ "input": [
+ {
+ "type": "input_image",
+ "image_url": "https://example.org/a.png",
+ "detail": "low",
+ }
+ ]
+ },
+ {"input": [{"type": "reasoning", "encrypted_content": "foreign-openai-blob"}]},
+ {
+ "input": [
+ {
+ "type": "reasoning",
+ "content": [{"type": "reasoning_text", "text": "unsigned"}],
+ }
+ ]
+ },
+ {
+ "tools": [
+ {
+ "type": "custom",
+ "name": "grammar",
+ "format": {"type": "grammar", "definition": "x"},
+ }
+ ]
+ },
+ {"tools": [{"type": "web_search"}]},
+ {"text": {"verbosity": "high"}},
+ {"text": {"format": {"type": "json_object"}}},
+ {"metadata": {"unrepresentable": "value"}},
+ {"reasoning": {"summary": "detailed"}},
+ {"include": ["web_search_call.action.sources"]},
+ {"truncation": "auto"},
+ {"future_control": {"required": True}},
+ ],
+)
+def test_unrepresentable_input_is_explicitly_rejected(payload: JsonObject) -> None:
+ with pytest.raises(ResponsesConversionError):
+ _build(payload)
+
+
+def test_json_schema_output_preserves_structure_and_descriptive_metadata() -> None:
+ built = _build(
+ {
+ "text": {
+ "format": {
+ "type": "json_schema",
+ "name": "answer",
+ "description": "Final answer",
+ "schema": {
+ "type": "object",
+ "properties": {"n": {"type": "integer"}},
+ "required": ["n"],
+ "additionalProperties": False,
+ },
+ "strict": True,
+ }
+ }
+ }
+ )
+ assert built.body["output_config"] == {
+ "format": {
+ "type": "json_schema",
+ "schema": {
+ "type": "object",
+ "properties": {"n": {"type": "integer"}},
+ "required": ["n"],
+ "additionalProperties": False,
+ "title": "answer",
+ "description": "Final answer",
+ },
+ }
+ }
+
+
+ "payload",
+ [
+ {"input": [{"type": []}]},
+ {"tools": [{"type": {}}]},
+ {"tool_choice": {"type": []}},
+ {"input": [{"role": [], "content": "hi"}]},
+ {"truncation": {}},
+ {"reasoning": {"summary": []}},
+ ],
+)
+def test_malformed_discriminators_produce_conversion_errors(
+ payload: JsonObject,
+) -> None:
+ with pytest.raises(ResponsesConversionError):
+ _build(payload)
diff --git a/tests/core/openai_responses/test_reasoning_replay.py b/tests/core/openai_responses/test_reasoning_replay.py
new file mode 100644
index 00000000..aa830e90
--- /dev/null
+++ b/tests/core/openai_responses/test_reasoning_replay.py
@@ -0,0 +1,178 @@
+"""Signed native replay cannot leak into a different egress protocol."""
+
+import base64
+import json
+
+import pytest
+
+from free_claude_code.core.anthropic import ReasoningReplayMode
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.openai_responses import (
+ OpenAIResponsesRequest,
+ ReasoningBlockState,
+ ResponsesConversionError,
+ build_native_responses_request,
+ build_responses_chat_request,
+ reasoning_output_item,
+)
+from free_claude_code.core.openai_responses.reasoning_replay import (
+ MessagesReplayOrigin,
+ decode_messages_reasoning,
+ encode_messages_reasoning,
+)
+from free_claude_code.core.reasoning import ReasoningPolicy
+
+_ORIGIN = MessagesReplayOrigin("github_copilot/anthropic_messages", "upstream")
+
+
+ "block",
+ [
+ {
+ "type": "thinking",
+ "thinking": "hello 🐍",
+ "signature": "opaque",
+ "extension": {"a": 1},
+ },
+ {"type": "thinking", "thinking": "", "signature": "signature-only"},
+ {"type": "redacted_thinking", "data": "opaque-data"},
+ ],
+)
+def test_replay_round_trip_preserves_exact_native_block(block: JsonObject) -> None:
+ carrier = encode_messages_reasoning(block, origin=_ORIGIN)
+ assert (
+ decode_messages_reasoning(carrier, replay_scope=_ORIGIN.replay_scope) == block
+ )
+ with pytest.raises(ResponsesConversionError, match="provenance"):
+ decode_messages_reasoning(
+ carrier, replay_scope="another-provider/anthropic_messages"
+ )
+
+
+ "carrier",
+ [
+ "openai-opaque",
+ "fcc:anthropic-reasoning:v2:e30",
+ "fcc:anthropic-reasoning:v1:!bad",
+ "fcc:anthropic-reasoning:v1:e30", # empty JSON object
+ "fcc:anthropic-reasoning:v1:W10", # JSON array
+ ],
+)
+def test_malformed_or_foreign_replay_rejected(carrier: str) -> None:
+ with pytest.raises(ResponsesConversionError):
+ decode_messages_reasoning(carrier, replay_scope=_ORIGIN.replay_scope)
+
+
+def test_missing_signature_is_not_accepted_as_signed_history() -> None:
+ data = {
+ "protocol": "anthropic_messages",
+ "replay_scope": _ORIGIN.replay_scope,
+ "source_model": "m",
+ "block": {"type": "thinking", "thinking": "visible-only"},
+ }
+ carrier = (
+ "fcc:anthropic-reasoning:v1:"
+ + base64.urlsafe_b64encode(json.dumps(data).encode()).decode()
+ )
+ with pytest.raises(ResponsesConversionError, match="signature"):
+ decode_messages_reasoning(carrier, replay_scope=_ORIGIN.replay_scope)
+
+
+def test_completed_reasoning_keeps_both_display_and_opaque_replay() -> None:
+ carrier = encode_messages_reasoning(
+ {"type": "thinking", "thinking": "visible", "signature": "opaque"},
+ origin=_ORIGIN,
+ )
+ state = ReasoningBlockState(
+ 0, 0, "rs_1", text_parts=["vis", "ible"], encrypted_content=carrier
+ )
+ item = reasoning_output_item(state, status="completed")
+ assert item["content"] == [{"type": "reasoning_text", "text": "visible"}]
+ assert item["encrypted_content"] == carrier
+ for egress in ("chat", "responses"):
+ request = OpenAIResponsesRequest.model_validate({"model": "m", "input": [item]})
+ with pytest.raises(ResponsesConversionError, match="Messages upstream"):
+ if egress == "chat":
+ build_responses_chat_request(
+ request, reasoning_replay=ReasoningReplayMode.REASONING_CONTENT
+ )
+ else:
+ build_native_responses_request(
+ request, model="m", reasoning=ReasoningPolicy()
+ )
+
+
+def test_singleton_reasoning_item_cannot_bypass_egress_guard() -> None:
+ carrier = encode_messages_reasoning(
+ {"type": "redacted_thinking", "data": "opaque"}, origin=_ORIGIN
+ )
+ request = OpenAIResponsesRequest(
+ model="m", input={"type": "reasoning", "encrypted_content": carrier}
+ )
+ with pytest.raises(ResponsesConversionError, match="Messages upstream"):
+ build_native_responses_request(request, model="m", reasoning=ReasoningPolicy())
+ with pytest.raises(ResponsesConversionError, match="Messages upstream"):
+ build_responses_chat_request(
+ request, reasoning_replay=ReasoningReplayMode.REASONING_CONTENT
+ )
+
+
[email protected]("value", [True, False])
+def test_responses_wire_limit_rejects_boolean_json(value: object) -> None:
+ with pytest.raises(ValueError, match="boolean"):
+ OpenAIResponsesRequest.model_validate(
+ {
+ "model": "m",
+ "input": "hi",
+ "max_output_tokens": value,
+ }
+ )
+
+
+ "extension",
+ ["NaN", "Infinity", "-Infinity", "1e999", "[" * 1100 + "0" + "]" * 1100],
+ ids=["nan", "infinity", "negative-infinity", "overflow", "deep"],
+)
+def test_carrier_cannot_hide_non_json_numbers_or_excessive_nesting(
+ extension: str,
+) -> None:
+ raw = (
+ '{"protocol":"anthropic_messages","replay_scope":"github_copilot/anthropic_messages",'
+ '"source_model":"m","block":{"type":"thinking","thinking":"ok","signature":"sig","extension":'
+ + extension
+ + "}}"
+ )
+ carrier = (
+ "fcc:anthropic-reasoning:v1:" + base64.urlsafe_b64encode(raw.encode()).decode()
+ )
+ with pytest.raises(ResponsesConversionError):
+ decode_messages_reasoning(carrier, replay_scope=_ORIGIN.replay_scope)
+
+
+def test_encoder_rejects_non_finite_extension_values() -> None:
+ with pytest.raises(ResponsesConversionError, match="finite"):
+ encode_messages_reasoning(
+ {
+ "type": "thinking",
+ "thinking": "ok",
+ "signature": "sig",
+ "extension": float("nan"),
+ },
+ origin=_ORIGIN,
+ )
+
+
+def test_decoder_rejects_unpaired_surrogate_before_http_serialization() -> None:
+ raw = (
+ '{"protocol":"anthropic_messages","replay_scope":"github_copilot/anthropic_messages",'
+ '"source_model":"m","block":{"type":"thinking","thinking":"'
+ + chr(92)
+ + 'ud800","signature":"sig"}}'
+ )
+ carrier = (
+ "fcc:anthropic-reasoning:v1:" + base64.urlsafe_b64encode(raw.encode()).decode()
+ )
+ with pytest.raises(ResponsesConversionError):
+ decode_messages_reasoning(carrier, replay_scope=_ORIGIN.replay_scope)
diff --git a/tests/core/openai_responses/test_responses_from_messages_stream.py b/tests/core/openai_responses/test_responses_from_messages_stream.py
new file mode 100644
index 00000000..0de34ff8
--- /dev/null
+++ b/tests/core/openai_responses/test_responses_from_messages_stream.py
@@ -0,0 +1,427 @@
+"""Native Messages events preserve Responses identity, replay and completion."""
+
+from collections.abc import Mapping
+from typing import cast
+
+import pytest
+
+from free_claude_code.core.anthropic.native import (
+ NativeMessagesError,
+ NativeMessagesOptions,
+)
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_lines
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.core.json_types import JsonObject, JsonValue
+from free_claude_code.core.openai_responses import (
+ AnthropicToResponsesStream,
+ OpenAIResponsesRequest,
+ build_responses_messages_request,
+)
+from free_claude_code.core.openai_responses.reasoning_replay import (
+ MessagesReplayOrigin,
+ decode_messages_reasoning,
+)
+
+_SCOPE = "github_copilot/anthropic_messages"
+
+
+def _stream(*, tools: list[JsonObject] | None = None) -> AnthropicToResponsesStream:
+ request = OpenAIResponsesRequest(model="public", input="hi", tools=tools)
+ prepared = build_responses_messages_request(
+ request, options=NativeMessagesOptions("upstream", 4096), replay_scope=_SCOPE
+ )
+ return AnthropicToResponsesStream(
+ request,
+ public_model="public",
+ tool_identities=prepared.tool_identities,
+ replay_origin=MessagesReplayOrigin(_SCOPE, "upstream"),
+ )
+
+
+def _feed(
+ stream: AnthropicToResponsesStream, kind: str, **fields: JsonValue
+) -> list[JsonObject]:
+ chunks = stream.feed(kind, {"type": kind, **fields})
+ return [
+ cast(JsonObject, event.data)
+ for event in parse_sse_lines("".join(chunks).splitlines())
+ ]
+
+
+def _start(stream: AnthropicToResponsesStream) -> list[JsonObject]:
+ return _feed(
+ stream,
+ "message_start",
+ message={
+ "id": "native-id",
+ "type": "message",
+ "role": "assistant",
+ "model": "upstream",
+ "content": [],
+ "usage": {
+ "input_tokens": 11,
+ "cache_read_input_tokens": 7,
+ "cache_creation_input_tokens": 5,
+ "output_tokens": 0,
+ },
+ },
+ )
+
+
+def _end(
+ stream: AnthropicToResponsesStream,
+ reason: str = "end_turn",
+ *,
+ usage: JsonValue = None,
+) -> list[JsonObject]:
+ events = _feed(
+ stream,
+ "message_delta",
+ delta={"stop_reason": reason, "stop_sequence": None},
+ usage=usage if usage is not None else {"output_tokens": 19},
+ )
+ assert not stream.completed
+ events += _feed(stream, "message_stop")
+ return events
+
+
+def test_text_thinking_and_redacted_blocks_keep_order_replay_and_exact_usage() -> None:
+ stream = _stream()
+ events = _start(stream)
+ events += _feed(
+ stream,
+ "content_block_start",
+ index=3,
+ content_block={"type": "thinking", "thinking": "", "extension": {"x": 1}},
+ )
+ events += _feed(
+ stream,
+ "content_block_delta",
+ index=3,
+ delta={"type": "thinking_delta", "thinking": "think"},
+ )
+ events += _feed(
+ stream,
+ "content_block_delta",
+ index=3,
+ delta={"type": "signature_delta", "signature": "sig-"},
+ )
+ events += _feed(
+ stream,
+ "content_block_delta",
+ index=3,
+ delta={"type": "signature_delta", "signature": "end"},
+ )
+ events += _feed(stream, "content_block_stop", index=3)
+ events += _feed(
+ stream,
+ "content_block_start",
+ index=5,
+ content_block={"type": "redacted_thinking", "data": "opaque"},
+ )
+ events += _feed(stream, "content_block_stop", index=5)
+ events += _feed(
+ stream,
+ "content_block_start",
+ index=9,
+ content_block={"type": "text", "text": "Hello "},
+ )
+ events += _feed(
+ stream,
+ "content_block_delta",
+ index=9,
+ delta={"type": "text_delta", "text": "world"},
+ )
+ events += _feed(stream, "content_block_stop", index=9)
+ events += _end(
+ stream,
+ usage={
+ "input_tokens": 11,
+ "cache_read_input_tokens": 7,
+ "cache_creation_input_tokens": 5,
+ "cache_creation": {"ephemeral_5m_input_tokens": 5},
+ "output_tokens": 19,
+ "output_tokens_details": {"thinking_tokens": 4},
+ },
+ )
+ assert stream.completed
+ assert [event["sequence_number"] for event in events] == list(range(len(events)))
+ response = events[-1]["response"]
+ assert isinstance(response, Mapping)
+ assert response["id"] == cast(Mapping[str, JsonValue], events[0]["response"])["id"]
+ assert response["model"] == "public" and response["status"] == "completed"
+ output = response["output"]
+ assert isinstance(output, list) and len(output) == 3
+ first = output[0]
+ assert isinstance(first, Mapping)
+ assert first["content"] == [{"type": "reasoning_text", "text": "think"}]
+ assert decode_messages_reasoning(
+ cast(str, first["encrypted_content"]), replay_scope=_SCOPE
+ ) == {
+ "type": "thinking",
+ "thinking": "think",
+ "signature": "sig-end",
+ "extension": {"x": 1},
+ }
+ assert decode_messages_reasoning(
+ cast(str, cast(Mapping[str, JsonValue], output[1])["encrypted_content"]),
+ replay_scope=_SCOPE,
+ ) == {"type": "redacted_thinking", "data": "opaque"}
+ assert cast(Mapping[str, JsonValue], output[2])["content"] == [
+ {"type": "output_text", "text": "Hello world", "annotations": []}
+ ]
+ assert response["usage"] == {
+ "input_tokens": 23,
+ "input_tokens_details": {
+ "cached_tokens": 7,
+ "cache_creation_tokens": 5,
+ "cache_creation": {"ephemeral_5m_input_tokens": 5},
+ },
+ "output_tokens": 19,
+ "output_tokens_details": {"reasoning_tokens": 4},
+ "total_tokens": 42,
+ }
+ assert (
+ "".join(
+ cast(str, event["delta"])
+ for event in events
+ if event["type"] == "response.output_text.delta"
+ )
+ == "Hello world"
+ )
+ assert sum(event["type"] == "response.completed" for event in events) == 1
+
+
+def test_parallel_tools_preserve_call_ids_namespace_and_emit_arguments_once() -> None:
+ stream = _stream(
+ tools=[
+ {
+ "type": "namespace",
+ "name": "ops",
+ "tools": [{"type": "function", "name": "lookup"}],
+ },
+ {"type": "custom", "name": "command"},
+ ]
+ )
+ events = _start(stream)
+ events += _feed(
+ stream,
+ "content_block_start",
+ index=4,
+ content_block={
+ "type": "tool_use",
+ "id": "call-a",
+ "name": "ops__lookup",
+ "input": {},
+ "caller": {"type": "direct"},
+ },
+ )
+ events += _feed(
+ stream,
+ "content_block_start",
+ index=7,
+ content_block={
+ "type": "tool_use",
+ "id": "call-b",
+ "name": "command",
+ "input": {},
+ },
+ )
+ for fragment in ('{"q":', '"ok"}'):
+ events += _feed(
+ stream,
+ "content_block_delta",
+ index=4,
+ delta={"type": "input_json_delta", "partial_json": fragment},
+ )
+ events += _feed(
+ stream,
+ "content_block_delta",
+ index=7,
+ delta={"type": "input_json_delta", "partial_json": '{"input":"pwd"}'},
+ )
+ assert not any(
+ event["type"] == "response.function_call_arguments.delta" for event in events
+ )
+ events += _feed(stream, "content_block_stop", index=7)
+ events += _feed(stream, "content_block_stop", index=4)
+ events += _end(stream, "tool_use")
+ response = cast(Mapping[str, JsonValue], events[-1]["response"])
+ output = cast(list[JsonObject], response["output"])
+ assert output[0]["call_id"] == "call-a" and output[0]["namespace"] == "ops"
+ assert output[0]["name"] == "lookup" and output[0]["arguments"] == '{"q":"ok"}'
+ assert output[1]["call_id"] == "call-b" and output[1]["input"] == "pwd"
+ assert output[0]["id"] != output[0]["call_id"]
+ assert [
+ event["delta"]
+ for event in events
+ if event["type"] == "response.function_call_arguments.delta"
+ ] == ['{"q":"ok"}']
+ assert [
+ event["delta"]
+ for event in events
+ if event["type"] == "response.custom_tool_call_input.delta"
+ ] == ["pwd"]
+
+
+def test_signature_only_thinking_has_replay_without_invented_visible_text() -> None:
+ stream = _stream()
+ _start(stream)
+ _feed(
+ stream,
+ "content_block_start",
+ index=0,
+ content_block={"type": "thinking", "thinking": ""},
+ )
+ _feed(
+ stream,
+ "content_block_delta",
+ index=0,
+ delta={"type": "signature_delta", "signature": "opaque"},
+ )
+ _feed(stream, "content_block_stop", index=0)
+ events = _end(stream)
+ response = cast(Mapping[str, JsonValue], events[-1]["response"])
+ item = cast(list[JsonObject], response["output"])[0]
+ assert "content" not in item
+ assert (
+ decode_messages_reasoning(
+ cast(str, item["encrypted_content"]), replay_scope=_SCOPE
+ )["thinking"]
+ == ""
+ )
+ assert "output_tokens_details" not in cast(
+ Mapping[str, JsonValue], response["usage"]
+ )
+
+
+def test_max_tokens_is_incomplete_and_success_waits_for_native_message_stop() -> None:
+ stream = _stream()
+ _start(stream)
+ _feed(
+ stream,
+ "content_block_start",
+ index=0,
+ content_block={"type": "text", "text": "partial"},
+ )
+ _feed(stream, "content_block_stop", index=0)
+ events = _end(stream, "max_tokens")
+ assert events[-1]["type"] == "response.incomplete"
+ assert cast(Mapping[str, JsonValue], events[-1]["response"])[
+ "incomplete_details"
+ ] == {"reason": "max_output_tokens"}
+
+
[email protected]("usage", [{}, {"output_tokens": True}, {"output_tokens": -1}])
+def test_invalid_final_usage_does_not_publish_stale_initial_counts(
+ usage: JsonObject,
+) -> None:
+ stream = _stream()
+ _start(stream)
+ events = _end(stream, usage=usage)
+ assert cast(Mapping[str, JsonValue], events[-1]["response"])["usage"] is None
+
+
+def test_failure_retains_partial_text_without_completing_partial_tool_arguments() -> (
+ None
+):
+ stream = _stream(tools=[{"type": "function", "name": "lookup"}])
+ _start(stream)
+ _feed(
+ stream,
+ "content_block_start",
+ index=0,
+ content_block={"type": "text", "text": "partial text"},
+ )
+ _feed(
+ stream,
+ "content_block_start",
+ index=1,
+ content_block={"type": "tool_use", "id": "c", "name": "lookup", "input": {}},
+ )
+ _feed(
+ stream,
+ "content_block_delta",
+ index=1,
+ delta={"type": "input_json_delta", "partial_json": '{"x":'},
+ )
+ failure = ExecutionFailure(FailureKind.TIMEOUT, 504, "timed out", False)
+ events = [
+ event.data
+ for event in parse_sse_lines(
+ "".join(stream.terminal_failure(failure)).splitlines()
+ )
+ ]
+ assert [event["type"] for event in events] == ["response.failed"]
+ output = events[0]["response"]["output"]
+ assert [item["status"] for item in output] == ["incomplete", "incomplete"]
+ assert output[0]["content"][0]["text"] == "partial text"
+ assert output[1]["arguments"] == ""
+ assert stream.terminal_failure(failure) == []
+ with pytest.raises(NativeMessagesError, match="terminal"):
+ _feed(stream, "message_stop")
+
+
+ "arguments", ['{"input":1}', '{"extra":"x"}', '{"input":"ok","extra":1}']
+)
+def test_malformed_custom_tool_wrapper_cannot_become_completed_output(
+ arguments: str,
+) -> None:
+ stream = _stream(tools=[{"type": "custom", "name": "command"}])
+ _start(stream)
+ _feed(
+ stream,
+ "content_block_start",
+ index=0,
+ content_block={"type": "tool_use", "id": "c", "name": "command", "input": {}},
+ )
+ _feed(
+ stream,
+ "content_block_delta",
+ index=0,
+ delta={"type": "input_json_delta", "partial_json": arguments},
+ )
+ with pytest.raises(NativeMessagesError, match="exactly one text"):
+ _feed(stream, "content_block_stop", index=0)
+ failure = ExecutionFailure(FailureKind.UPSTREAM, 502, "invalid tool", False)
+ failed = parse_sse_lines("".join(stream.terminal_failure(failure)).splitlines())[
+ -1
+ ].data
+ output = failed["response"]["output"]
+ assert len(output) == 1
+ assert output[0]["call_id"] == "c" and output[0]["status"] == "incomplete"
+
+
+def test_terminal_usage_omits_missing_cache_and_provisional_thinking_details() -> None:
+ stream = _stream()
+ _feed(
+ stream,
+ "message_start",
+ message={
+ "id": "native",
+ "type": "message",
+ "role": "assistant",
+ "model": "upstream",
+ "content": [],
+ "usage": {
+ "input_tokens": 3,
+ "output_tokens": 0,
+ "output_tokens_details": {"thinking_tokens": 0},
+ },
+ },
+ )
+ _feed(
+ stream,
+ "content_block_start",
+ index=0,
+ content_block={"type": "thinking", "thinking": "thought", "signature": "sig"},
+ )
+ _feed(stream, "content_block_stop", index=0)
+ events = _end(stream)
+ response = cast(Mapping[str, JsonValue], events[-1]["response"])
+ assert response["usage"] == {
+ "input_tokens": 3,
+ "output_tokens": 19,
+ "total_tokens": 22,
+ }
diff --git a/tests/providers/copilot_support.py b/tests/providers/copilot_support.py
new file mode 100644
index 00000000..2d68b188
--- /dev/null
+++ b/tests/providers/copilot_support.py
@@ -0,0 +1,94 @@
+"""Deterministic native-account doubles; never read the real Copilot profile."""
+
+import asyncio
+
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.providers.anthropic_messages.request_policy import (
+ MessagesModelCapabilities,
+)
+from free_claude_code.providers.endpoint import HttpEndpoint
+from free_claude_code.providers.github_copilot.types import (
+ CopilotEgress,
+ CopilotEndpoint,
+ CopilotIdentity,
+ CopilotModel,
+)
+
+
+def opened_gate() -> asyncio.Event:
+ gate = asyncio.Event()
+ gate.set()
+ return gate
+
+
+def model(name: str = "model") -> CopilotModel:
+ return CopilotModel(ProviderModelInfo(model_id=name), MessagesModelCapabilities())
+
+
+class FakeSession:
+ def __init__(self, model_id: str) -> None:
+ self.model_id = model_id
+ self.value = CopilotEndpoint(
+ CopilotEgress.CHAT,
+ HttpEndpoint("https://copilot.invalid", {}, "credential"),
+ )
+ self.endpoint_calls = 0
+ self.closed = False
+ self.endpoint_gate = opened_gate()
+
+ async def endpoint(self) -> CopilotEndpoint:
+ self.endpoint_calls += 1
+ await self.endpoint_gate.wait()
+ return self.value
+
+ async def close(self) -> None:
+ self.closed = True
+
+
+class FakeRuntime:
+ def __init__(self) -> None:
+ self.current_identity: CopilotIdentity | None = CopilotIdentity(
+ "github.com", "octocat"
+ )
+ self.available: tuple[CopilotModel, ...] = (model(),)
+ self.start_calls = 0
+ self.model_calls = 0
+ self.session_calls = 0
+ self.close_calls = 0
+ self.model_error: Exception | None = None
+ self.sessions: list[FakeSession] = []
+ self.model_gate = opened_gate()
+ self.model_entered = asyncio.Event()
+ self.session_gate = opened_gate()
+ self.session_entered = asyncio.Event()
+ self.close_gate = opened_gate()
+ self.close_entered = asyncio.Event()
+
+ async def start(self) -> None:
+ self.start_calls += 1
+
+ async def identity(self) -> CopilotIdentity | None:
+ return self.current_identity
+
+ async def models(self) -> tuple[CopilotModel, ...]:
+ self.model_calls += 1
+ self.model_entered.set()
+ await self.model_gate.wait()
+ if self.model_error is not None:
+ raise self.model_error
+ return self.available
+
+ async def session(self, model_id: str) -> FakeSession:
+ self.session_calls += 1
+ self.session_entered.set()
+ await self.session_gate.wait()
+ result = FakeSession(model_id)
+ self.sessions.append(result)
+ return result
+
+ async def close(self) -> None:
+ self.close_calls += 1
+ self.close_entered.set()
+ await self.close_gate.wait()
+ for session in self.sessions:
+ await session.close()
diff --git a/tests/providers/fixtures/copilot_responses_changing_ids.json b/tests/providers/fixtures/copilot_responses_changing_ids.json
new file mode 100644
index 00000000..b44a4aa6
--- /dev/null
+++ b/tests/providers/fixtures/copilot_responses_changing_ids.json
@@ -0,0 +1,129 @@
+{
+ "source": "Authorized single HTTP capture 2026-09-05T04:30:23Z; IDs replaced by stable SHA256 labels.",
+ "sdk_correlation_equal": true,
+ "events": [
+ {
+ "type": "response.created",
+ "sequence_number": 0,
+ "response": {
+ "id": "id_c8f386bc86037e1afde70d019c73b6714fe8a1b7b01c76d9f85935456b7ca387",
+ "status": "in_progress",
+ "output": []
+ }
+ },
+ {
+ "type": "response.in_progress",
+ "sequence_number": 1,
+ "response": {
+ "id": "id_9ecb532eac9032646eb883aa898c56c969d256d476b0e32772057cd5ca5832e5",
+ "status": "in_progress",
+ "output": []
+ }
+ },
+ {
+ "type": "response.output_item.added",
+ "sequence_number": 2,
+ "output_index": 0,
+ "item": {
+ "type": "function_call",
+ "id": "id_9459fa53fc044d23942a2c1d47354f0c5c43fa20591b16df7ba9a8f0decaad9c",
+ "call_id": "id_71c0d69bf173aa38abde809d9a6a144a18dd72c38e926886862830643ba0b9cb",
+ "status": "in_progress",
+ "name": "fcc_echo",
+ "arguments": ""
+ }
+ },
+ {
+ "type": "response.function_call_arguments.delta",
+ "sequence_number": 3,
+ "output_index": 0,
+ "item_id": "id_05d30648f3c1c439349b4e34f72705b43094f1d7ed3ca8dc43f5160d8d3ccdad",
+ "delta": "{\""
+ },
+ {
+ "type": "response.function_call_arguments.delta",
+ "sequence_number": 4,
+ "output_index": 0,
+ "item_id": "id_5e26a41ba6bf446355a32fff01410c45192d9cff3b32301ae92a95ca240a16b3",
+ "delta": "value"
+ },
+ {
+ "type": "response.function_call_arguments.delta",
+ "sequence_number": 5,
+ "output_index": 0,
+ "item_id": "id_5ea6eae02feb670dc902ca4e86bc19ca474adb7b5c2d276991438a22631ef630",
+ "delta": "\":\""
+ },
+ {
+ "type": "response.function_call_arguments.delta",
+ "sequence_number": 6,
+ "output_index": 0,
+ "item_id": "id_fde5db27f4191b641d6c05b0226c57a0b3de856feec7df19f0002128347f41d4",
+ "delta": "FCC"
+ },
+ {
+ "type": "response.function_call_arguments.delta",
+ "sequence_number": 7,
+ "output_index": 0,
+ "item_id": "id_44c17f4af94e756e7843c9ebda857c1f53daff07b84f8eebd77c4515edf96adb",
+ "delta": "_TOOL"
+ },
+ {
+ "type": "response.function_call_arguments.delta",
+ "sequence_number": 8,
+ "output_index": 0,
+ "item_id": "id_a467fdb3b0b017e62e0d87cf280fcfa7a63d7cd7df7b8c209a3c3406b0435365",
+ "delta": "_OK"
+ },
+ {
+ "type": "response.function_call_arguments.delta",
+ "sequence_number": 9,
+ "output_index": 0,
+ "item_id": "id_e7add14b42bc53a74597cf75d44b71aaffd8885f89acea0ad3cbbe4f11fd3743",
+ "delta": "\"}"
+ },
+ {
+ "type": "response.function_call_arguments.done",
+ "sequence_number": 10,
+ "output_index": 0,
+ "item_id": "id_ff4ebb3c1a1315660697e657971baf4813946b674d951e6c8b3281d09dbca338",
+ "arguments": "{\"value\":\"FCC_TOOL_OK\"}"
+ },
+ {
+ "type": "response.output_item.done",
+ "sequence_number": 11,
+ "output_index": 0,
+ "item": {
+ "type": "function_call",
+ "id": "id_8533a45fc22302692561032244e6ddac18e0f441f1606c1e4069ee622b342d8a",
+ "call_id": "id_71c0d69bf173aa38abde809d9a6a144a18dd72c38e926886862830643ba0b9cb",
+ "status": "completed",
+ "name": "fcc_echo",
+ "arguments": "{\"value\":\"FCC_TOOL_OK\"}"
+ }
+ },
+ {
+ "type": "response.completed",
+ "sequence_number": 12,
+ "response": {
+ "id": "id_6705cd78e54695d5dc99961a6c095a2f738ecc8091e2102349bac94c2766871d",
+ "status": "completed",
+ "output": [
+ {
+ "type": "function_call",
+ "id": "id_c3951eb1f6206b11fa383bc25af0663d45dae5b75840ba815640d956025e48f0",
+ "call_id": "id_71c0d69bf173aa38abde809d9a6a144a18dd72c38e926886862830643ba0b9cb",
+ "status": "completed",
+ "name": "fcc_echo",
+ "arguments": "{\"value\":\"FCC_TOOL_OK\"}"
+ }
+ ],
+ "usage": {
+ "input_tokens": 91,
+ "output_tokens": 21,
+ "total_tokens": 112
+ }
+ }
+ }
+ ]
+}
diff --git a/tests/providers/test_anthropic_messages_transport.py b/tests/providers/test_anthropic_messages_transport.py
new file mode 100644
index 00000000..0a7ba49a
--- /dev/null
+++ b/tests/providers/test_anthropic_messages_transport.py
@@ -0,0 +1,541 @@
+"""Native Messages attempts preserve protocol, commitment and resource ownership."""
+
+import asyncio
+import json
+from collections.abc import AsyncIterator, Callable
+
+import httpx
+import pytest
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.openai_responses import OpenAIResponsesRequest
+from free_claude_code.providers.admission import ProviderAdmissionController
+from free_claude_code.providers.anthropic_messages.transport import (
+ AnthropicMessagesTransport,
+)
+from free_claude_code.providers.endpoint import HttpEndpoint
+from free_claude_code.providers.http import maybe_await_aclose
+from tests.providers.support import immediate_admission
+
+
+class Endpoint:
+ def __init__(self) -> None:
+ self.refreshes: list[bool] = []
+ self.token = "original"
+ self.base_url = "https://native.invalid/v1/"
+
+ async def endpoint(self, *, force_refresh: bool = False) -> HttpEndpoint:
+ self.refreshes.append(force_refresh)
+ return HttpEndpoint(
+ self.base_url,
+ {
+ "Authorization": "Bearer fresh"
+ if force_refresh
+ else f"Bearer {self.token}",
+ "Anthropic-Version": "2023-06-01",
+ },
+ )
+
+
[email protected]("started", [False, True])
[email protected]("kind", ["authentication_error", "permission_error"])
+async def test_precommit_sse_auth_failure_refreshes_once(
+ started: bool, kind: str
+) -> None:
+ calls = 0
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal calls
+ calls += 1
+ events = (
+ _events()
+ if calls > 1
+ else [
+ *(_events()[:1] if started else []),
+ {"type": "error", "error": {"type": kind}},
+ ]
+ )
+ return httpx.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ stream=Wire([_sse(*events)]),
+ )
+
+ endpoint = Endpoint()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ result = parse_sse_text(
+ "".join(
+ [
+ event
+ async for event in _stream(
+ _transport(client), endpoint, responses=True
+ )
+ ]
+ )
+ )
+ assert calls == 2 and endpoint.refreshes == [False, True]
+ assert sum(event.event == "response.created" for event in result) == 1
+
+
[email protected]("separator", ["\u2028", "\u2029", "\u0085"])
+async def test_unicode_line_characters_remain_inside_sse_text(separator: str) -> None:
+ text = f"left{separator}right"
+ async with httpx.AsyncClient(
+ transport=httpx.MockTransport(
+ lambda _: httpx.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ stream=Wire([_sse(*_events(text))]),
+ )
+ )
+ ) as client:
+ endpoint = Endpoint()
+ output = parse_sse_text(
+ "".join(
+ [
+ event
+ async for event in _stream(
+ _transport(client), endpoint, responses=True
+ )
+ ]
+ )
+ )
+ assert endpoint.refreshes == [False]
+ assert output[-1].data["response"]["output"][0]["content"][0]["text"] == text
+
+
+class Wire(httpx.AsyncByteStream):
+ def __init__(
+ self,
+ chunks: list[bytes | Exception],
+ *,
+ closed: Callable[[], None] | None = None,
+ close_gate: asyncio.Event | None = None,
+ ) -> None:
+ self.chunks = chunks
+ self.closed = False
+ self._on_close = closed
+ self._close_gate = close_gate
+
+ async def __aiter__(self) -> AsyncIterator[bytes]:
+ for chunk in self.chunks:
+ if isinstance(chunk, Exception):
+ raise chunk
+ yield chunk
+
+ async def aclose(self) -> None:
+ if self._close_gate is not None:
+ await self._close_gate.wait()
+ self.closed = True
+ if self._on_close is not None:
+ self._on_close()
+
+
+def _sse(*events: JsonObject) -> bytes:
+ return "".join(
+ f"event: {event['type']}\ndata: {json.dumps(event, ensure_ascii=False)}\n\n"
+ for event in events
+ ).encode()
+
+
+def _events(text: str = "hello", stop: str = "end_turn") -> list[JsonObject]:
+ return [
+ {
+ "type": "message_start",
+ "message": {
+ "id": "upstream-id",
+ "type": "message",
+ "model": "native",
+ "role": "assistant",
+ "content": [],
+ "usage": {"input_tokens": 3, "output_tokens": 0},
+ },
+ },
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "text", "text": ""},
+ },
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "text_delta", "text": text},
+ },
+ {"type": "content_block_stop", "index": 0},
+ {
+ "type": "message_delta",
+ "delta": {"stop_reason": stop},
+ "usage": {"output_tokens": 2},
+ },
+ {"type": "message_stop"},
+ ]
+
+
+def _transport(
+ client: httpx.AsyncClient, admission: ProviderAdmissionController | None = None
+) -> AnthropicMessagesTransport:
+ return AnthropicMessagesTransport(
+ client=client,
+ admission=admission or immediate_admission(max_attempts=2),
+ provider_name="TEST",
+ replay_scope="test/messages",
+ read_timeout_s=3,
+ )
+
+
+def _stream(
+ transport: AnthropicMessagesTransport, endpoint: Endpoint, *, responses: bool
+) -> AsyncIterator[str]:
+ if responses:
+ return transport.stream_responses(
+ OpenAIResponsesRequest(model="native", input="hi"),
+ endpoint_context=endpoint,
+ response_model="public",
+ )
+ return transport.stream_messages(
+ MessagesRequest(
+ model="native",
+ messages=[{"role": "user", "content": "hi"}],
+ betas=["test-beta"],
+ ),
+ endpoint_context=endpoint,
+ response_model="public",
+ )
+
+
[email protected]("responses", [False, True])
[email protected]("versioned_base", [False, True])
+async def test_fragmented_messages_http_keeps_native_path_and_public_identity(
+ responses: bool,
+ versioned_base: bool,
+) -> None:
+ raw = _sse(*_events())
+ wire = Wire([raw[index : index + 7] for index in range(0, len(raw), 7)])
+ requests: list[httpx.Request] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ requests.append(request)
+ return httpx.Response(
+ 200, headers={"content-type": "text/event-stream"}, stream=wire
+ )
+
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ endpoint = Endpoint()
+ endpoint.base_url = (
+ "https://native.invalid/v1/" if versioned_base else "https://native.invalid"
+ )
+ output = parse_sse_text(
+ "".join(
+ [
+ event
+ async for event in _stream(
+ _transport(client), endpoint, responses=responses
+ )
+ ]
+ )
+ )
+ assert not client.is_closed
+ assert wire.closed and len(requests) == 1
+ assert requests[0].url.path == "/v1/messages"
+ assert requests[0].headers["Authorization"] == "Bearer original"
+ assert requests[0].headers["anthropic-version"] == "2023-06-01"
+ assert requests[0].headers.get_list("anthropic-version") == ["2023-06-01"]
+ body = json.loads(requests[0].content)
+ assert body["stream"] is True and body["model"] == "native"
+ assert body["max_tokens"] > 0
+ if responses:
+ assert output[-1].data["response"]["model"] == "public"
+ assert output[-1].event == "response.completed"
+ else:
+ assert requests[0].headers["anthropic-beta"] == "test-beta"
+ assert output[0].data["message"]["id"] == "upstream-id"
+ assert output[0].data["message"]["model"] == "public"
+ assert output[-1].event == "message_stop"
+
+
[email protected]("status", [401, 403])
+async def test_unauthorized_refresh_uses_same_budget_and_closes_before_next_request(
+ status: int,
+) -> None:
+ endpoint = Endpoint()
+ wires: list[Wire] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ if wires:
+ assert wires[0].closed
+ assert request.headers["Authorization"] == "Bearer fresh"
+ wire = Wire([b'{"error":"expired"}' if not wires else _sse(*_events())])
+ wires.append(wire)
+ return httpx.Response(
+ status if len(wires) == 1 else 200,
+ headers={"content-type": "text/event-stream"},
+ stream=wire,
+ )
+
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ assert [
+ item async for item in _stream(_transport(client), endpoint, responses=True)
+ ]
+ assert endpoint.refreshes == [False, True] and all(wire.closed for wire in wires)
+
+
+async def test_repeated_unauthorized_cannot_create_unbounded_auth_retry() -> None:
+ calls = 0
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal calls
+ calls += 1
+ return httpx.Response(401, json={"error": {"type": "authentication_error"}})
+
+ endpoint = Endpoint()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ with pytest.raises(ExecutionFailure) as caught:
+ _ = [
+ event
+ async for event in _stream(_transport(client), endpoint, responses=True)
+ ]
+ assert caught.value.kind is FailureKind.AUTHENTICATION
+ assert calls == 2 and endpoint.refreshes == [False, True]
+
+
+ "first",
+ [
+ b"event: content_block_delta\ndata: {bad}\n\n",
+ _sse(*_events()[:3]),
+ b'event: error\ndata: {"type":"error","error":{"type":"overloaded_error"}}\n\n',
+ ],
+)
+async def test_early_malformed_truncated_and_overloaded_attempts_retry_invisibly(
+ first: bytes,
+) -> None:
+ calls = 0
+ wires: list[Wire] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal calls
+ calls += 1
+ wire = Wire([first if calls == 1 else _sse(*_events("final"))])
+ wires.append(wire)
+ return httpx.Response(
+ 200, headers={"content-type": "text/event-stream"}, stream=wire
+ )
+
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ result = "".join(
+ [
+ event
+ async for event in _stream(
+ _transport(client), Endpoint(), responses=True
+ )
+ ]
+ )
+ events = parse_sse_text(result)
+ assert calls == 2 and all(wire.closed for wire in wires)
+ assert sum(event.event == "response.created" for event in events) == 1
+ assert "final" in result and "hello" not in result
+
+
[email protected]("responses", [False, True])
[email protected]("auth", [False, True])
+async def test_committed_failure_never_retries_or_emits_success(
+ responses: bool,
+ auth: bool,
+) -> None:
+ calls = 0
+ wire = Wire(
+ [
+ _sse(*_events("x" * 70_000)[:3]),
+ _sse({"type": "error", "error": {"type": "authentication_error"}})
+ if auth
+ else httpx.ReadTimeout("stalled"),
+ ]
+ )
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal calls
+ calls += 1
+ return httpx.Response(
+ 200, headers={"content-type": "text/event-stream"}, stream=wire
+ )
+
+ chunks: list[str] = []
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ stream = _stream(_transport(client), Endpoint(), responses=responses)
+ if responses:
+ chunks = [chunk async for chunk in stream]
+ else:
+ with pytest.raises(ExecutionFailure):
+ async for chunk in stream:
+ chunks.append(chunk)
+ events = parse_sse_text("".join(chunks))
+ assert calls == 1 and wire.closed
+ assert not any(
+ event.event in {"message_stop", "response.completed"} for event in events
+ )
+ if responses:
+ assert sum(event.event == "response.failed" for event in events) == 1
+ assert events[-1].data["response"]["output"][0]["status"] == "incomplete"
+
+
[email protected]("error_code", [False, True])
+async def test_context_window_stop_is_nonretryable_canonical_failure(
+ error_code: bool,
+) -> None:
+ calls = 0
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal calls
+ calls += 1
+ return httpx.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ stream=Wire(
+ [
+ _sse(
+ {
+ "type": "error",
+ "error": {
+ "type": "invalid_request_error",
+ "code": "context_length_exceeded",
+ },
+ }
+ )
+ if error_code
+ else _sse(*_events(stop="model_context_window_exceeded"))
+ ]
+ ),
+ )
+
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ with pytest.raises(ExecutionFailure) as caught:
+ _ = [
+ event
+ async for event in _stream(
+ _transport(client), Endpoint(), responses=True
+ )
+ ]
+ assert caught.value.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED and calls == 1
+
+
+async def test_cancelled_consumer_closes_response_before_releasing_admission() -> None:
+ gate = asyncio.Event()
+ first = Wire([_sse(*_events("x" * 70_000))], close_gate=gate)
+ calls = 0
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal calls
+ calls += 1
+ if calls == 2:
+ assert request.headers["Authorization"] == "Bearer new"
+ return httpx.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ stream=first if calls == 1 else Wire([_sse(*_events())]),
+ )
+
+ admission = ProviderAdmissionController(
+ provider_name="TEST",
+ rate_limit=1_000_000,
+ rate_window=1,
+ max_concurrency=1,
+ max_attempts=2,
+ base_delay=0,
+ max_delay=0,
+ jitter=0,
+ )
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ transport = _transport(client, admission)
+ stream = _stream(transport, Endpoint(), responses=True)
+ assert await anext(stream)
+ close = asyncio.create_task(maybe_await_aclose(stream))
+ next_endpoint = Endpoint()
+ next_stream = _stream(transport, next_endpoint, responses=True)
+ next_request = asyncio.ensure_future(anext(next_stream))
+ await asyncio.sleep(0)
+ await asyncio.sleep(0)
+ assert calls == 1 and not close.done() and not next_request.done()
+ assert next_endpoint.refreshes == []
+ next_endpoint.token = "new"
+ gate.set()
+ await close
+ assert await next_request
+ await maybe_await_aclose(next_stream)
+ assert first.closed and calls == 2
+
+
+async def test_task_cancellation_closes_live_http_response() -> None:
+ entered = asyncio.Event()
+
+ class BlockingWire(Wire):
+ async def __aiter__(self) -> AsyncIterator[bytes]:
+ yield _sse(*_events("x" * 70_000)[:3])
+ entered.set()
+ await asyncio.Event().wait()
+
+ wire = BlockingWire([])
+ async with httpx.AsyncClient(
+ transport=httpx.MockTransport(
+ lambda _: httpx.Response(
+ 200, headers={"content-type": "text/event-stream"}, stream=wire
+ )
+ )
+ ) as client:
+ stream = _stream(_transport(client), Endpoint(), responses=True)
+
+ async def consume() -> None:
+ async for _ in stream:
+ pass
+
+ task = asyncio.create_task(consume())
+ await entered.wait()
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert wire.closed
+
+
+async def test_auth_refresh_cannot_exceed_single_attempt_budget() -> None:
+ endpoint = Endpoint()
+ async with httpx.AsyncClient(
+ transport=httpx.MockTransport(
+ lambda _: httpx.Response(401, json={"error": "expired"})
+ )
+ ) as client:
+ with pytest.raises(ExecutionFailure):
+ _ = [
+ event
+ async for event in _stream(
+ _transport(client, immediate_admission(max_attempts=1)),
+ endpoint,
+ responses=True,
+ )
+ ]
+ assert endpoint.refreshes == [False]
+
+
+async def test_preflight_rejects_invalid_conversion_without_request_io() -> None:
+ async with httpx.AsyncClient() as client:
+ transport = _transport(client)
+ with pytest.raises(InvalidRequestError):
+ transport.preflight_responses(
+ OpenAIResponsesRequest(
+ model="native", input=[{"type": "input_file", "file_id": "remote"}]
+ )
+ )
diff --git a/tests/providers/test_endpoint_context_transports.py b/tests/providers/test_endpoint_context_transports.py
new file mode 100644
index 00000000..b09ce8bb
--- /dev/null
+++ b/tests/providers/test_endpoint_context_transports.py
@@ -0,0 +1,301 @@
+"""Both OpenAI egresses borrow isolated request credentials and one retry budget."""
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+
+import httpx2
+import pytest
+from openai import AsyncOpenAI
+
+from free_claude_code.core.anthropic import ReasoningReplayMode
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.openai_responses import OpenAIResponsesRequest
+from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY
+from free_claude_code.providers.endpoint import HttpEndpoint
+from free_claude_code.providers.openai_chat import (
+ NO_REASONING,
+ OpenAIChatProfile,
+ OpenAIChatProvider,
+ OpenAIChatRequestPolicy,
+)
+from free_claude_code.providers.openai_responses import OpenAIResponsesTransport
+from tests.providers.support import immediate_admission, make_provider_config
+
+
+class Context:
+ def __init__(
+ self, name: str, *, token: str | None = "key", authorization: str | None = None
+ ) -> None:
+ self.name = name
+ self.token = token
+ self.authorization = authorization
+ self.calls: list[bool] = []
+
+ async def endpoint(self, *, force_refresh: bool = False) -> HttpEndpoint:
+ self.calls.append(force_refresh)
+ headers = {"X-Session": self.name}
+ if self.authorization:
+ headers["authorization"] = self.authorization
+ return HttpEndpoint(
+ f"https://{self.name}.invalid/",
+ headers,
+ f"{self.token}-fresh" if force_refresh and self.token else self.token,
+ )
+
+
+def _response(request: httpx2.Request) -> httpx2.Response:
+ if request.url.path.endswith("/responses"):
+ payload = {
+ "type": "response.completed",
+ "response": {
+ "id": "resp",
+ "object": "response",
+ "created_at": 0,
+ "status": "completed",
+ "model": "upstream",
+ "output": [],
+ "usage": {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
+ },
+ }
+ else:
+ payload = {
+ "id": "chat",
+ "object": "chat.completion.chunk",
+ "created": 0,
+ "model": "upstream",
+ "choices": [
+ {
+ "index": 0,
+ "delta": {"role": "assistant", "content": "ok"},
+ "finish_reason": "stop",
+ }
+ ],
+ "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2},
+ }
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=f"data: {json.dumps(payload)}\n\ndata: [DONE]\n\n",
+ )
+
+
+def _transport(
+ client: AsyncOpenAI, *, responses: bool, pool: httpx2.AsyncBaseTransport
+) -> OpenAIChatProvider | OpenAIResponsesTransport:
+ admission = immediate_admission(max_attempts=3)
+ if responses:
+ return OpenAIResponsesTransport(
+ client=client,
+ admission=admission,
+ provider_name="TEST",
+ read_timeout_s=3,
+ log_raw_sse_events=False,
+ endpoint_transport=pool,
+ )
+ return OpenAIChatProvider(
+ make_provider_config(None, "https://original.invalid"),
+ profile=OpenAIChatProfile(
+ OpenAIChatRequestPolicy("TEST", ReasoningReplayMode.REASONING_CONTENT),
+ NO_REASONING,
+ ),
+ admission=admission,
+ client=client,
+ endpoint_transport=pool,
+ )
+
+
+def _stream(
+ transport: OpenAIChatProvider | OpenAIResponsesTransport,
+ context: Context,
+ *,
+ responses_ingress: bool,
+) -> AsyncIterator[str]:
+ if responses_ingress:
+ return transport.stream_responses(
+ OpenAIResponsesRequest(model="upstream", input="hi"),
+ input_tokens=1,
+ request_id=None,
+ response_model="public",
+ reasoning=DEFAULT_REASONING_POLICY,
+ endpoint_context=context,
+ )
+ return transport.stream_messages(
+ MessagesRequest(model="upstream", messages=[{"role": "user", "content": "hi"}]),
+ input_tokens=1,
+ request_id=None,
+ response_model="public",
+ reasoning=DEFAULT_REASONING_POLICY,
+ endpoint_context=context,
+ )
+
+
+async def _consume(stream: AsyncIterator[str]) -> None:
+ assert [event async for event in stream]
+
+
[email protected]("responses", [False, True])
[email protected]("responses_ingress", [False, True])
+async def test_concurrent_endpoint_views_do_not_share_headers_or_close_base(
+ responses: bool, responses_ingress: bool
+) -> None:
+ seen: list[httpx2.Request] = []
+
+ def handler(request: httpx2.Request) -> httpx2.Response:
+ seen.append(request)
+ return _response(request)
+
+ pool = httpx2.MockTransport(handler)
+ async with AsyncOpenAI(
+ api_key="base-secret",
+ organization="old-org",
+ project="old-project",
+ base_url="https://original.invalid",
+ default_headers={"X-Old": "base"},
+ default_query={"old": "secret"},
+ http_client=httpx2.AsyncClient(
+ transport=pool,
+ auth=("old-user", "old-password"),
+ headers={"X-Secret": "old"},
+ params={"old-http": "secret"},
+ cookies={"old-cookie": "secret"},
+ ),
+ ) as client:
+ transport = _transport(client, responses=responses, pool=pool)
+ a = Context("a", authorization="Bearer session-a")
+ b = Context("b", token=None)
+ await asyncio.gather(
+ _consume(_stream(transport, a, responses_ingress=responses_ingress)),
+ _consume(_stream(transport, b, responses_ingress=responses_ingress)),
+ )
+ for request in seen:
+ assert "X-Old" not in request.headers and not request.url.query
+ assert "X-Secret" not in request.headers and "Cookie" not in request.headers
+ assert (
+ "OpenAI-Organization" not in request.headers
+ and "OpenAI-Project" not in request.headers
+ )
+ if request.url.host == "a.invalid":
+ assert request.headers.get_list("authorization") == ["Bearer session-a"]
+ assert request.headers["X-Session"] == "a"
+ else:
+ assert "authorization" not in request.headers
+ assert request.headers["X-Session"] == "b"
+ assert len(seen) == 2
+ assert client.api_key == "base-secret" and client.organization == "old-org"
+ if isinstance(transport, OpenAIChatProvider):
+ await transport.cleanup()
+ assert not client.is_closed()
+
+
[email protected]("responses", [False, True])
[email protected]("responses_ingress", [False, True])
[email protected]("status", [401, 403])
+async def test_http_auth_refresh_is_request_scoped_and_bounded(
+ responses: bool, responses_ingress: bool, status: int
+) -> None:
+ calls = 0
+
+ def handler(request: httpx2.Request) -> httpx2.Response:
+ nonlocal calls
+ calls += 1
+ if calls == 1:
+ assert request.headers["Authorization"] == "Bearer key"
+ return httpx2.Response(status, json={"error": {"message": "expired"}})
+ assert request.headers["Authorization"] == "Bearer key-fresh"
+ return _response(request)
+
+ pool = httpx2.MockTransport(handler)
+ async with AsyncOpenAI(
+ api_key="base",
+ base_url="https://unused.invalid",
+ http_client=httpx2.AsyncClient(transport=pool),
+ ) as client:
+ context = Context("a")
+ await _consume(
+ _stream(
+ _transport(client, responses=responses, pool=pool),
+ context,
+ responses_ingress=responses_ingress,
+ )
+ )
+ assert calls == 2 and context.calls == [False, True]
+
+
[email protected]("responses", [False, True])
+async def test_repeated_rejection_cannot_refresh_again_with_budget_remaining(
+ responses: bool,
+) -> None:
+ calls = 0
+
+ def handler(request: httpx2.Request) -> httpx2.Response:
+ nonlocal calls
+ calls += 1
+ return httpx2.Response(
+ 401,
+ headers={"x-should-retry": "true"},
+ json={"error": {"message": "expired"}},
+ )
+
+ pool = httpx2.MockTransport(handler)
+ async with AsyncOpenAI(
+ api_key="base",
+ base_url="https://unused.invalid",
+ http_client=httpx2.AsyncClient(transport=pool),
+ ) as client:
+ context = Context("a")
+ with pytest.raises(ExecutionFailure):
+ await _consume(
+ _stream(
+ _transport(client, responses=responses, pool=pool),
+ context,
+ responses_ingress=True,
+ )
+ )
+ assert calls == 2 and context.calls == [False, True]
+
+
[email protected]("responses_ingress", [False, True])
+ "responses,wrapped", [(False, True), (True, True), (True, False)]
+)
+async def test_stream_authentication_refreshes_before_commit(
+ responses: bool, responses_ingress: bool, wrapped: bool
+) -> None:
+ calls = 0
+
+ def handler(request: httpx2.Request) -> httpx2.Response:
+ nonlocal calls
+ calls += 1
+ if calls > 1:
+ return _response(request)
+ failure = {
+ "code": "invalid_api_key",
+ "type": "authentication_error",
+ "message": "expired",
+ }
+ payload = {"error": failure} if wrapped else {**failure, "type": "error"}
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=f"data: {json.dumps(payload)}\n\n",
+ )
+
+ pool = httpx2.MockTransport(handler)
+ async with AsyncOpenAI(
+ api_key="base", http_client=httpx2.AsyncClient(transport=pool)
+ ) as client:
+ context = Context("a")
+ await _consume(
+ _stream(
+ _transport(client, responses=responses, pool=pool),
+ context,
+ responses_ingress=responses_ingress,
+ )
+ )
+ assert calls == 2 and context.calls == [False, True]
diff --git a/tests/providers/test_github_copilot_auth.py b/tests/providers/test_github_copilot_auth.py
new file mode 100644
index 00000000..1a5cdf8d
--- /dev/null
+++ b/tests/providers/test_github_copilot_auth.py
@@ -0,0 +1,259 @@
+"""FCC opt-in and interactive login over isolated native-account test doubles."""
+
+import asyncio
+import json
+from collections.abc import Callable
+from contextlib import suppress
+from pathlib import Path
+
+import pytest
+
+from free_claude_code.application.connected_accounts import (
+ ConnectedAccountLoginMode,
+ ConnectedAccountState,
+)
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.providers.github_copilot.auth import CopilotAuthManager
+from free_claude_code.providers.github_copilot.login import DeviceChallenge
+from free_claude_code.providers.github_copilot.types import (
+ CopilotIdentity,
+ CopilotUnavailable,
+)
+from tests.providers.copilot_support import FakeRuntime
+
+DEVICE = ConnectedAccountLoginMode.DEVICE
+
+
+async def settled(manager: CopilotAuthManager) -> None:
+ async with asyncio.timeout(2):
+ while manager.status().state is ConnectedAccountState.CONNECTING:
+ await asyncio.sleep(0)
+
+
+async def test_existing_native_profile_connects_persists_only_safe_state_and_restarts_lazily(
+ tmp_path: Path,
+) -> None:
+ runtime = FakeRuntime()
+ path = tmp_path / "state.json"
+ manager = CopilotAuthManager(state_path=path, runtime_factory=lambda: runtime)
+ assert not manager.is_connected() and runtime.start_calls == 0
+ await manager.start_login(DEVICE)
+ await settled(manager)
+ assert manager.is_connected() and manager.status().display_identity == "@octocat"
+ state = json.loads(path.read_text())
+ assert set(state) == {"schema_version", "enabled", "identity", "revision"}
+ assert state["enabled"] is True
+ await manager.close()
+ replacement = FakeRuntime()
+ restarted = CopilotAuthManager(state_path=path, runtime_factory=lambda: replacement)
+ assert restarted.is_connected() and replacement.start_calls == 0
+ assert list(await restarted.models()) == ["model"]
+ await restarted.disconnect()
+ assert json.loads(path.read_text())["enabled"] is False
+ assert replacement.close_calls == 1
+ await restarted.close()
+
+
+async def test_device_login_challenge_and_fresh_validation_after_cli_finishes(
+ tmp_path: Path,
+) -> None:
+ signed_out, signed_in = FakeRuntime(), FakeRuntime()
+ signed_out.current_identity = None
+ runtimes = iter((signed_out, signed_in))
+ release = asyncio.Event()
+
+ async def login(callback: Callable[[DeviceChallenge], None]) -> None:
+ callback(DeviceChallenge("https://github.com/login/device", "ABCD-1234"))
+ await release.wait()
+
+ manager = CopilotAuthManager(
+ state_path=tmp_path / "state.json",
+ runtime_factory=lambda: next(runtimes),
+ login_flow=login,
+ )
+ await manager.start_login(DEVICE)
+ async with asyncio.timeout(2):
+ while manager.status().user_code is None:
+ await asyncio.sleep(0)
+ status = manager.status()
+ assert not status.connected and status.user_code == "ABCD-1234"
+ assert (
+ status.supported_login_modes == (DEVICE,)
+ and status.default_login_mode is DEVICE
+ )
+ assert signed_out.close_calls == 1
+ release.set()
+ await settled(manager)
+ assert manager.is_connected() and signed_in.model_calls == 1
+ await manager.close()
+
+
+async def test_concurrent_connect_coalesces_and_cancel_prevents_stale_publication(
+ tmp_path: Path,
+) -> None:
+ signed_out, signed_in = FakeRuntime(), FakeRuntime()
+ signed_out.current_identity = None
+ runtimes = iter((signed_out, signed_in))
+ entered = asyncio.Event()
+
+ async def login(_callback: Callable[[DeviceChallenge], None]) -> None:
+ entered.set()
+ # Simulate a native grant that finishes as cancellation arrives.
+ with suppress(asyncio.CancelledError):
+ await asyncio.Event().wait()
+
+ manager = CopilotAuthManager(
+ state_path=tmp_path / "state.json",
+ runtime_factory=lambda: next(runtimes),
+ login_flow=login,
+ )
+ first, second = await asyncio.gather(
+ manager.start_login(DEVICE), manager.start_login(DEVICE)
+ )
+ assert first.attempt_id == second.attempt_id
+ await entered.wait()
+ await manager.cancel_login()
+ assert not manager.is_connected()
+ assert signed_in.close_calls == 1
+ assert manager.status().state is ConnectedAccountState.DISCONNECTED
+ await manager.close()
+
+
+async def test_login_timeout_cleans_up_and_reports_local_deadline(
+ tmp_path: Path,
+) -> None:
+ runtime = FakeRuntime()
+ runtime.current_identity = None
+ exited = asyncio.Event()
+
+ async def login(_callback: Callable[[DeviceChallenge], None]) -> None:
+ try:
+ await asyncio.Event().wait()
+ finally:
+ exited.set()
+
+ manager = CopilotAuthManager(
+ state_path=tmp_path / "state.json",
+ runtime_factory=lambda: runtime,
+ login_flow=login,
+ login_timeout_s=0.02,
+ )
+ await manager.start_login(DEVICE)
+ await settled(manager)
+ assert exited.is_set() and not manager.is_connected()
+ assert "FCC's time limit" in (manager.status().message or "")
+ await manager.close()
+
+
+async def test_profile_change_invalidates_revision_before_credentials_leave_lease(
+ tmp_path: Path,
+) -> None:
+ runtime = FakeRuntime()
+ manager = CopilotAuthManager(
+ state_path=tmp_path / "state.json", runtime_factory=lambda: runtime
+ )
+ await manager.start_login(DEVICE)
+ await settled(manager)
+ revision = manager.status().revision
+ async with manager.lease("model") as lease:
+ runtime.current_identity = CopilotIdentity("github.com", "other")
+ with pytest.raises(ExecutionFailure) as error:
+ await lease.endpoint()
+ assert error.value.status_code == 401
+ assert not manager.is_connected() and manager.status().revision > revision
+ assert runtime.close_calls == 0
+ await manager.close()
+ assert runtime.close_calls == 1
+
+
+async def test_disconnect_invalidates_new_admission_and_waits_for_response_lease(
+ tmp_path: Path,
+) -> None:
+ runtime = FakeRuntime()
+ manager = CopilotAuthManager(
+ state_path=tmp_path / "state.json", runtime_factory=lambda: runtime
+ )
+ await manager.start_login(DEVICE)
+ await settled(manager)
+ async with manager.lease("model"):
+ task = asyncio.create_task(manager.disconnect())
+ await asyncio.sleep(0)
+ assert not manager.is_connected() and not task.done()
+ with pytest.raises(ExecutionFailure):
+ async with manager.lease("model"):
+ pytest.fail("new request admitted after disconnect")
+ await task
+ assert runtime.close_calls == 1
+ await manager.close()
+
+
+async def test_failed_persistence_never_reports_connected(tmp_path: Path) -> None:
+ runtime = FakeRuntime()
+ runtime.model_gate.clear()
+ path = tmp_path / "state.json"
+ manager = CopilotAuthManager(state_path=path, runtime_factory=lambda: runtime)
+ await manager.start_login(DEVICE)
+ await runtime.model_entered.wait()
+ path.unlink()
+ path.mkdir()
+ runtime.model_gate.set()
+ await settled(manager)
+ assert (
+ not manager.is_connected()
+ and manager.status().state is ConnectedAccountState.ERROR
+ )
+ assert runtime.close_calls == 1
+ await manager.close()
+
+
+async def test_unsupported_login_mode_does_not_start_runtime(tmp_path: Path) -> None:
+ runtime = FakeRuntime()
+ manager = CopilotAuthManager(
+ state_path=tmp_path / "state.json", runtime_factory=lambda: runtime
+ )
+ with pytest.raises(InvalidRequestError):
+ await manager.start_login(ConnectedAccountLoginMode.BROWSER)
+ assert runtime.start_calls == 0
+ await manager.close()
+
+
+async def test_cancel_reports_and_retains_failed_runtime_cleanup(
+ tmp_path: Path,
+) -> None:
+ class Runtime(FakeRuntime):
+ fail_close = True
+
+ async def close(self) -> None:
+ if self.fail_close:
+ raise CopilotUnavailable("Owned runtime could not be stopped.")
+ await super().close()
+
+ runtime = Runtime()
+ runtime.model_gate.clear()
+ manager = CopilotAuthManager(
+ state_path=tmp_path / "state.json", runtime_factory=lambda: runtime
+ )
+ await manager.start_login(DEVICE)
+ await runtime.model_entered.wait()
+ cancellation = asyncio.create_task(manager.cancel_login())
+ await asyncio.sleep(0)
+ runtime.model_gate.set()
+ try:
+ status = await cancellation
+ assert status.state is ConnectedAccountState.ERROR
+ assert "cleanup" in (status.message or "").lower()
+ assert not status.connected
+ finally:
+ runtime.fail_close = False
+ await manager.close()
+ assert runtime.close_calls == 1
diff --git a/tests/providers/test_github_copilot_broker.py b/tests/providers/test_github_copilot_broker.py
new file mode 100644
index 00000000..efaa4767
--- /dev/null
+++ b/tests/providers/test_github_copilot_broker.py
@@ -0,0 +1,199 @@
+"""Discovery, account binding and response-owned endpoint lease contracts."""
+
+import asyncio
+import time
+from dataclasses import replace
+
+import pytest
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.providers.github_copilot.broker import CopilotBroker
+from free_claude_code.providers.github_copilot.types import (
+ CopilotAuthenticationRequired,
+ CopilotEgress,
+ CopilotIdentity,
+ CopilotUnavailable,
+)
+from tests.providers.copilot_support import FakeRuntime, model
+
+
+async def test_cold_discovery_coalesces_and_cancelled_waiter_does_not_cancel_owner() -> (
+ None
+):
+ runtime = FakeRuntime()
+ runtime.model_gate.clear()
+ broker = CopilotBroker(runtime)
+ first = asyncio.create_task(broker.snapshot())
+ await runtime.model_entered.wait()
+ second = asyncio.create_task(broker.snapshot())
+ first.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await first
+ runtime.model_gate.set()
+ assert list(await second) == ["model"]
+ assert runtime.start_calls == runtime.model_calls == 1
+ await broker.close()
+
+
+async def test_refresh_failure_preserves_last_good_snapshot() -> None:
+ runtime = FakeRuntime()
+ broker = CopilotBroker(runtime)
+ previous = await broker.snapshot()
+ runtime.model_error = CopilotUnavailable("offline")
+ with pytest.raises(CopilotUnavailable):
+ await broker.snapshot(refresh=True)
+ assert await broker.snapshot() is previous
+ await broker.close()
+
+
+async def test_concurrent_leases_reuse_session_and_refresh_known_expiry() -> None:
+ runtime = FakeRuntime()
+ broker = CopilotBroker(runtime)
+ async with broker.lease("model") as first, broker.lease("model") as second:
+ assert runtime.session_calls == 1
+ session = runtime.sessions[0]
+ await first.endpoint()
+ await second.endpoint()
+ assert session.endpoint_calls == 1
+ session.value = replace(session.value, expires_at=time.time() + 10)
+ await first.endpoint(force_refresh=True)
+ await second.endpoint()
+ assert session.endpoint_calls == 3
+ await broker.close()
+ assert session.closed
+
+
+async def test_identity_change_and_removed_models_cannot_publish_new_credentials() -> (
+ None
+):
+ runtime = FakeRuntime()
+ broker = CopilotBroker(runtime)
+ async with broker.lease("model") as lease:
+ runtime.current_identity = CopilotIdentity("github.com", "other")
+ with pytest.raises(CopilotAuthenticationRequired):
+ await lease.endpoint()
+ runtime.current_identity = CopilotIdentity("github.com", "octocat")
+ runtime.available = (model("other-model"),)
+ await broker.snapshot(refresh=True)
+ with pytest.raises(InvalidRequestError):
+ await lease.endpoint()
+ with pytest.raises(InvalidRequestError):
+ async with broker.lease("model"):
+ pytest.fail("removed model was leased")
+ await broker.close()
+
+
+async def test_lease_rejects_protocol_change_or_expired_credential() -> None:
+ runtime = FakeRuntime()
+ broker = CopilotBroker(runtime)
+ async with broker.lease("model") as lease:
+ session = runtime.sessions[0]
+ session.value = replace(session.value, egress=CopilotEgress.MESSAGES)
+ with pytest.raises(CopilotUnavailable, match="protocol"):
+ await lease.endpoint(force_refresh=True)
+ session.value = replace(session.value, expires_at=time.time() - 10)
+ with pytest.raises(CopilotUnavailable, match="expired"):
+ await lease.endpoint(force_refresh=True)
+ await broker.close()
+
+
+async def test_cancelled_close_waits_for_active_lease_and_released_lease_is_unusable() -> (
+ None
+):
+ runtime = FakeRuntime()
+ broker = CopilotBroker(runtime)
+ async with broker.lease("model") as lease:
+ task = asyncio.create_task(broker.close())
+ await asyncio.sleep(0)
+ task.cancel()
+ await asyncio.sleep(0)
+ assert not task.done() and runtime.close_calls == 0
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert runtime.close_calls == 1
+ with pytest.raises(CopilotUnavailable, match="closed"):
+ await lease.endpoint()
+
+
+async def test_cancelled_session_creation_is_drained_before_runtime_closes() -> None:
+ runtime = FakeRuntime()
+ runtime.session_gate.clear()
+ broker = CopilotBroker(runtime)
+
+ async def request() -> None:
+ async with broker.lease("model"):
+ pytest.fail("cancelled request admitted")
+
+ request_task = asyncio.create_task(request())
+ await runtime.session_entered.wait()
+ request_task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await request_task
+ close = asyncio.create_task(broker.close())
+ await asyncio.sleep(0)
+ assert runtime.close_calls == 0
+ runtime.session_gate.set()
+ await close
+ assert runtime.sessions[0].closed
+
+
+async def test_account_change_during_discovery_rejects_snapshot() -> None:
+ runtime = FakeRuntime()
+ runtime.model_gate.clear()
+ broker = CopilotBroker(runtime)
+ task = asyncio.create_task(broker.snapshot())
+ await runtime.model_entered.wait()
+ runtime.current_identity = CopilotIdentity("github.com", "other")
+ runtime.model_gate.set()
+ with pytest.raises(CopilotAuthenticationRequired):
+ await task
+ assert not broker.current_models
+ await broker.close()
+
+
+async def test_confirmed_empty_discovery_revokes_old_model_credentials() -> None:
+ runtime = FakeRuntime()
+ broker = CopilotBroker(runtime)
+ try:
+ async with broker.lease("model") as lease:
+ session = runtime.sessions[0]
+ runtime.available = ()
+ with pytest.raises(CopilotUnavailable, match="no enabled Copilot models"):
+ await broker.snapshot(refresh=True)
+ previous_endpoint_calls = session.endpoint_calls
+ with pytest.raises(InvalidRequestError):
+ await lease.endpoint(force_refresh=True)
+ assert session.endpoint_calls == previous_endpoint_calls
+ assert not broker.current_models
+ with pytest.raises((CopilotUnavailable, InvalidRequestError)):
+ async with broker.lease("model"):
+ pytest.fail("empty discovery left a removed model leasable")
+ finally:
+ await broker.close()
+
+
+ "identity", [None, CopilotIdentity("github.com", "other-account")]
+)
+async def test_cached_discovery_rejects_changed_or_signed_out_native_identity(
+ identity: CopilotIdentity | None,
+) -> None:
+ runtime = FakeRuntime()
+ broker = CopilotBroker(runtime)
+ try:
+ assert list(await broker.snapshot()) == ["model"]
+ runtime.current_identity = identity
+ with pytest.raises(CopilotAuthenticationRequired):
+ await broker.snapshot(refresh=False)
+ finally:
+ await broker.close()
diff --git a/tests/providers/test_github_copilot_login.py b/tests/providers/test_github_copilot_login.py
new file mode 100644
index 00000000..93f55f45
--- /dev/null
+++ b/tests/providers/test_github_copilot_login.py
@@ -0,0 +1,81 @@
+"""Device login owns pipe drainage even when cancellation races process spawn."""
+
+import asyncio
+from contextlib import suppress
+from unittest.mock import AsyncMock
+
+import pytest
+
+from free_claude_code.providers.github_copilot import login
+
+
+class Pipe(asyncio.StreamReader):
+ def __init__(self) -> None:
+ super().__init__()
+ self.drained = asyncio.Event()
+ self.feed_data(b"child output")
+
+ async def read(self, n: int = -1) -> bytes:
+ data = await super().read(n)
+ if not data:
+ self.drained.set()
+ return data
+
+
+class Child:
+ """Mirror subprocess wait's dependency on completion of both pipe transports."""
+
+ def __init__(self) -> None:
+ self.stdout = Pipe()
+ self.stderr = Pipe()
+ self.returncode: int | None = None
+ self.wait_entered = asyncio.Event()
+
+ def kill(self) -> None:
+ self.returncode = -1
+ self.stdout.feed_eof()
+ self.stderr.feed_eof()
+
+ async def wait(self) -> int:
+ self.wait_entered.set()
+ await self.stdout.drained.wait()
+ await self.stderr.drained.wait()
+ assert self.returncode is not None
+ return self.returncode
+
+
+async def test_cancel_during_spawn_drains_pipes_before_waiting_for_child(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ child = Child()
+ spawned, return_child = asyncio.Event(), asyncio.Event()
+
+ async def spawn(*_args: object, **_kwargs: object) -> Child:
+ spawned.set()
+ await return_child.wait()
+ return child
+
+ async def discard(pipe: Pipe) -> None:
+ while await pipe.read(1024):
+ pass
+
+ monkeypatch.setattr(login, "verified_cli_path", AsyncMock(return_value="inert-cli"))
+ monkeypatch.setattr(login.asyncio, "create_subprocess_exec", spawn)
+ task = asyncio.create_task(login.device_login(lambda _challenge: None))
+ await spawned.wait()
+ task.cancel()
+ return_child.set()
+ await child.wait_entered.wait()
+ try:
+ done, _ = await asyncio.wait({task}, timeout=1)
+ assert task in done, "login cancellation abandoned unread child pipes"
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert child.stdout.drained.is_set() and child.stderr.drained.is_set()
+ finally:
+ # Make the red run terminate cleanly too; this does not satisfy the assertion.
+ if not task.done():
+ await asyncio.gather(discard(child.stdout), discard(child.stderr))
+ with suppress(asyncio.CancelledError):
+ await task
diff --git a/tests/providers/test_github_copilot_provider.py b/tests/providers/test_github_copilot_provider.py
new file mode 100644
index 00000000..5219a5d4
--- /dev/null
+++ b/tests/providers/test_github_copilot_provider.py
@@ -0,0 +1,704 @@
+"""Connected-account dispatch preserves both ingresses across all three egresses."""
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+from dataclasses import replace
+from pathlib import Path
+
+import httpx
+import httpx2
+import pytest
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.stream_contracts import (
+ assert_anthropic_stream_contract,
+ parse_sse_text,
+ text_content,
+)
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.openai_responses import (
+ MessagesReplayOrigin,
+ OpenAIResponsesRequest,
+)
+from free_claude_code.core.openai_responses.reasoning_replay import (
+ encode_messages_reasoning,
+)
+from free_claude_code.core.reasoning import (
+ DEFAULT_REASONING_POLICY,
+ ReasoningEffort,
+ ReasoningPolicy,
+)
+from free_claude_code.providers.anthropic_messages.request_policy import (
+ MessagesModelCapabilities,
+)
+from free_claude_code.providers.endpoint import HttpEndpoint
+from free_claude_code.providers.github_copilot.auth import CopilotAuthManager
+from free_claude_code.providers.github_copilot.provider import GitHubCopilotProvider
+from free_claude_code.providers.github_copilot.types import (
+ CopilotEgress,
+ CopilotEndpoint,
+ CopilotModel,
+)
+from tests.providers.copilot_support import FakeRuntime, FakeSession
+from tests.providers.support import immediate_admission, make_provider_config
+from tests.providers.test_anthropic_messages_transport import _events as messages_events
+from tests.providers.test_anthropic_messages_transport import _sse as messages_sse
+from tests.providers.test_openai_responses_transport import (
+ _completed_event,
+ _text_delta,
+)
+from tests.providers.test_openai_responses_transport import (
+ _sse as responses_sse,
+)
+
+
+class Wire(httpx.AsyncByteStream, httpx2.AsyncByteStream):
+ def __init__(self, content: bytes) -> None:
+ self.content = content
+ self.closed = False
+ self.close_entered = asyncio.Event()
+ self.close_gate = asyncio.Event()
+ self.close_gate.set()
+ self.read_gate = asyncio.Event()
+ self.read_gate.set()
+ self.read_entered = asyncio.Event()
+
+ async def __aiter__(self) -> AsyncIterator[bytes]:
+ self.read_entered.set()
+ await self.read_gate.wait()
+ yield self.content
+
+ async def aclose(self) -> None:
+ self.close_entered.set()
+ await self.close_gate.wait()
+ self.closed = True
+
+
+class Runtime(FakeRuntime):
+ def __init__(self, egress: CopilotEgress) -> None:
+ super().__init__()
+ self.egress = egress
+ # Names deliberately do not identify the transport family.
+ self.name = (
+ "gpt-looking" if egress is CopilotEgress.MESSAGES else "claude-looking"
+ )
+ self.available = (
+ CopilotModel(
+ ProviderModelInfo(model_id=self.name, max_output_tokens=4096),
+ MessagesModelCapabilities(
+ max_output_tokens=4096,
+ adaptive_thinking="optional",
+ supports_output_effort=True,
+ supported_efforts=("low", "high"),
+ ),
+ ("none", "low", "high"),
+ "low",
+ ),
+ )
+
+ async def session(self, model_id: str) -> FakeSession:
+ session = await super().session(model_id)
+ session.value = CopilotEndpoint(
+ self.egress,
+ HttpEndpoint(
+ "https://copilot.invalid",
+ {"X-Session": f"session-{model_id}"},
+ "account-secret",
+ ),
+ )
+ return session
+
+
+class Harness:
+ def __init__(self, tmp_path: Path, egress: CopilotEgress) -> None:
+ self.runtime = Runtime(egress)
+ state = tmp_path / "copilot.json"
+ state.write_text(
+ json.dumps(
+ {
+ "schema_version": 1,
+ "revision": 3,
+ "enabled": True,
+ "identity": {"host": "github.com", "login": "octocat"},
+ }
+ ),
+ encoding="utf-8",
+ )
+ self.auth = CopilotAuthManager(
+ state_path=state, runtime_factory=lambda: self.runtime
+ )
+ self.seen: list[httpx.Request | httpx2.Request] = []
+ self.wires: list[Wire] = []
+ self.statuses: list[int] = []
+ self.block_close = False
+ self.block_read = False
+ self.messages_content = messages_sse(*messages_events("ok"))
+ self.responses_content = responses_sse(
+ _text_delta("ok"), _completed_event()
+ ).encode()
+ self.chat_content = (
+ "data: "
+ + json.dumps(
+ {
+ "id": "chat-id",
+ "object": "chat.completion.chunk",
+ "created": 0,
+ "model": "upstream",
+ "choices": [
+ {
+ "index": 0,
+ "delta": {"role": "assistant", "content": "ok"},
+ "finish_reason": "stop",
+ }
+ ],
+ "usage": {
+ "prompt_tokens": 3,
+ "completion_tokens": 2,
+ "total_tokens": 5,
+ },
+ }
+ )
+ + "\n\ndata: [DONE]\n\n"
+ ).encode()
+ self.provider = GitHubCopilotProvider(
+ make_provider_config(
+ None, "https://configuration.invalid", http_read_timeout=3
+ ),
+ auth=self.auth,
+ admission=immediate_admission(max_attempts=2),
+ messages_transport=httpx.MockTransport(self.messages),
+ openai_transport=httpx2.MockTransport(self.openai),
+ )
+
+ def wire(self, content: bytes) -> Wire:
+ wire = Wire(content)
+ if self.block_close:
+ wire.close_gate.clear()
+ if self.block_read:
+ wire.read_gate.clear()
+ self.wires.append(wire)
+ return wire
+
+ def messages(self, request: httpx.Request) -> httpx.Response:
+ self.seen.append(request)
+ status = self.statuses.pop(0) if self.statuses else 200
+ if status != 200:
+ return httpx.Response(
+ status,
+ headers={"set-cookie": "inherited=secret; Path=/"},
+ json={"error": {"message": "expired"}},
+ )
+ return httpx.Response(
+ 200,
+ headers={
+ "content-type": "text/event-stream",
+ "set-cookie": "inherited=secret; Path=/",
+ },
+ stream=self.wire(self.messages_content),
+ )
+
+ def openai(self, request: httpx2.Request) -> httpx2.Response:
+ self.seen.append(request)
+ status = self.statuses.pop(0) if self.statuses else 200
+ if status != 200:
+ return httpx2.Response(
+ status,
+ headers={"set-cookie": "inherited=secret; Path=/"},
+ json={"error": {"message": "expired"}},
+ )
+ content = (
+ self.responses_content
+ if request.url.path.endswith("/responses")
+ else self.chat_content
+ )
+ return httpx2.Response(
+ 200,
+ headers={
+ "content-type": "text/event-stream",
+ "set-cookie": "inherited=secret; Path=/",
+ },
+ stream=self.wire(content),
+ )
+
+ def stream(
+ self,
+ responses: bool,
+ *,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ history: bool = False,
+ ) -> AsyncIterator[str]:
+ request = _request(responses, self.runtime.name, history=history)
+ if isinstance(request, MessagesRequest):
+ return self.provider.stream_messages(
+ request, response_model="public-alias", reasoning=reasoning
+ )
+ return self.provider.stream_responses(
+ request, response_model="public-alias", reasoning=reasoning
+ )
+
+ async def close(self) -> None:
+ await self.provider.cleanup()
+ assert self.runtime.close_calls == 0
+ await self.auth.close()
+
+
+def _request(
+ responses: bool, model: str, *, history: bool = False
+) -> MessagesRequest | OpenAIResponsesRequest:
+ if responses:
+ return OpenAIResponsesRequest.model_validate(
+ {
+ "model": model,
+ "input": [
+ {
+ "role": "user",
+ "content": [
+ {"type": "input_text", "text": "hello"},
+ {
+ "type": "input_image",
+ "image_url": "https://images.invalid/picture.png",
+ },
+ ],
+ },
+ {
+ "type": "function_call",
+ "call_id": "call-owned",
+ "name": "read_file",
+ "arguments": '{"path":"file.txt"}',
+ },
+ {
+ "type": "function_call_output",
+ "call_id": "call-owned",
+ "output": "the file",
+ },
+ ]
+ if history
+ else "hello",
+ "tools": [
+ {
+ "type": "function",
+ "name": "read_file",
+ "parameters": {
+ "type": "object",
+ "properties": {"path": {"type": "string"}},
+ },
+ }
+ ]
+ if history
+ else None,
+ }
+ )
+ return MessagesRequest.model_validate(
+ {
+ "model": model,
+ "messages": [
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "hello"},
+ {
+ "type": "image",
+ "source": {
+ "type": "url",
+ "url": "https://images.invalid/picture.png",
+ },
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "call-owned",
+ "name": "read_file",
+ "input": {"path": "file.txt"},
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "call-owned",
+ "content": "the file",
+ }
+ ],
+ },
+ ]
+ if history
+ else [{"role": "user", "content": "hello"}],
+ "tools": [
+ {
+ "name": "read_file",
+ "input_schema": {
+ "type": "object",
+ "properties": {"path": {"type": "string"}},
+ },
+ }
+ ]
+ if history
+ else None,
+ }
+ )
+
+
+async def collect(stream: AsyncIterator[str]) -> str:
+ return "".join([event async for event in stream])
+
+
[email protected]("egress", list(CopilotEgress))
[email protected]("responses", [False, True])
+async def test_six_cells_use_metadata_and_preserve_text_usage_public_model_and_history(
+ tmp_path: Path, egress: CopilotEgress, responses: bool
+) -> None:
+ harness = Harness(tmp_path, egress)
+ try:
+ events = parse_sse_text(await collect(harness.stream(responses, history=True)))
+ assert len(harness.seen) == 1
+ request = harness.seen[0]
+ assert (
+ request.url.path
+ == {
+ CopilotEgress.MESSAGES: "/v1/messages",
+ CopilotEgress.RESPONSES: "/responses",
+ CopilotEgress.CHAT: "/chat/completions",
+ }[egress]
+ )
+ assert request.headers["X-Session"] == f"session-{harness.runtime.name}"
+ credential = (
+ "x-api-key" if egress is CopilotEgress.MESSAGES else "authorization"
+ )
+ assert "account-secret" in request.headers[credential]
+ body = json.loads(request.content)
+ assert body["model"] == harness.runtime.name
+ assert body["stream"] is True
+ raw = request.content.decode()
+ assert raw.count("call-owned") == 2
+ assert "https://images.invalid/picture.png" in raw
+ assert "file.txt" in raw and "the file" in raw
+ assert harness.wires[0].closed
+ assert not harness.runtime.sessions[0].closed
+ if responses:
+ assert events[-1].event == "response.completed"
+ assert events[-1].data["response"]["model"] == "public-alias"
+ assert events[-1].data["response"]["usage"]["output_tokens"] == 2
+ assert "ok" in "".join(event.raw for event in events)
+ else:
+ assert_anthropic_stream_contract(events)
+ assert text_content(events) == "ok"
+ assert events[0].data["message"]["model"] == "public-alias"
+ assert events[-2].data["usage"]["output_tokens"] == 2
+ finally:
+ await harness.close()
+
+
[email protected]("egress", list(CopilotEgress))
+async def test_auth_refresh_and_later_requests_never_inherit_response_cookies(
+ tmp_path: Path, egress: CopilotEgress
+) -> None:
+ harness = Harness(tmp_path, egress)
+ harness.statuses = [401]
+ try:
+ await collect(harness.stream(True))
+ await collect(harness.stream(True))
+ assert len(harness.seen) == 3
+ assert all("cookie" not in request.headers for request in harness.seen)
+ assert harness.runtime.sessions[0].endpoint_calls == 2
+ finally:
+ await harness.close()
+
+
[email protected]("egress", [CopilotEgress.CHAT, CopilotEgress.RESPONSES])
[email protected]("responses", [False, True])
+ "policy,wire_effort",
+ [
+ (DEFAULT_REASONING_POLICY, None),
+ (ReasoningPolicy.on(), "low"),
+ (ReasoningPolicy.on(effort=ReasoningEffort.HIGH), "high"),
+ (ReasoningPolicy.off(), "none"),
+ ],
+)
+async def test_non_messages_controls_use_advertised_efforts(
+ tmp_path: Path,
+ egress: CopilotEgress,
+ responses: bool,
+ policy: ReasoningPolicy,
+ wire_effort: str | None,
+) -> None:
+ harness = Harness(tmp_path, egress)
+ try:
+ await collect(harness.stream(responses, reasoning=policy))
+ body = json.loads(harness.seen[0].content)
+ if egress is CopilotEgress.CHAT:
+ assert body.get("reasoning_effort") == wire_effort
+ else:
+ assert body.get("reasoning", {}).get("effort") == wire_effort
+ finally:
+ await harness.close()
+
+
[email protected]("egress", [CopilotEgress.CHAT, CopilotEgress.RESPONSES])
+ "policy",
+ [
+ ReasoningPolicy.on(budget_tokens=1024),
+ ReasoningPolicy.on(effort=ReasoningEffort.MAX),
+ ReasoningPolicy.on(),
+ ReasoningPolicy.off(),
+ ],
+)
+async def test_unrepresentable_controls_reject_before_inference(
+ tmp_path: Path, egress: CopilotEgress, policy: ReasoningPolicy
+) -> None:
+ harness = Harness(tmp_path, egress)
+ harness.runtime.available = (
+ replace(
+ harness.runtime.available[0],
+ supported_efforts=("low",),
+ default_effort=None,
+ ),
+ )
+ try:
+ with pytest.raises(InvalidRequestError):
+ await collect(harness.stream(True, reasoning=policy))
+ assert not harness.seen
+ finally:
+ await harness.close()
+
+
+async def test_native_messages_uses_capabilities_and_exact_budget(
+ tmp_path: Path,
+) -> None:
+ harness = Harness(tmp_path, CopilotEgress.MESSAGES)
+ try:
+ request = MessagesRequest(
+ model=harness.runtime.name,
+ messages=[{"role": "user", "content": "hello"}],
+ max_tokens=99999,
+ )
+ await collect(
+ harness.provider.stream_messages(
+ request, reasoning=ReasoningPolicy.on(budget_tokens=1024)
+ )
+ )
+ body = json.loads(harness.seen[0].content)
+ assert body["max_tokens"] == 4096
+ assert body["thinking"] == {"type": "enabled", "budget_tokens": 1024}
+ finally:
+ await harness.close()
+
+
[email protected]("egress", list(CopilotEgress))
+async def test_native_reasoning_carrier_replays_only_to_messages_egress(
+ tmp_path: Path, egress: CopilotEgress
+) -> None:
+ harness = Harness(tmp_path, egress)
+ block: JsonObject = {
+ "type": "thinking",
+ "thinking": "private reasoning",
+ "signature": "exact-signature",
+ }
+ carrier = encode_messages_reasoning(
+ block,
+ origin=MessagesReplayOrigin("github_copilot/anthropic_messages", "prior-model"),
+ )
+ request = OpenAIResponsesRequest.model_validate(
+ {
+ "model": harness.runtime.name,
+ "input": [
+ {"type": "reasoning", "encrypted_content": carrier},
+ {
+ "role": "assistant",
+ "content": [{"type": "output_text", "text": "answer"}],
+ },
+ {"role": "user", "content": "continue"},
+ ],
+ }
+ )
+ try:
+ if egress is CopilotEgress.MESSAGES:
+ await collect(harness.provider.stream_responses(request))
+ body = json.loads(harness.seen[0].content)
+ assert body["messages"][0]["content"][0] == block
+ else:
+ with pytest.raises(
+ (InvalidRequestError, ValueError), match=r"[Rr]easoning"
+ ):
+ await collect(harness.provider.stream_responses(request))
+ assert not harness.seen
+ finally:
+ await harness.close()
+
+
[email protected]("egress", list(CopilotEgress))
+async def test_cancelled_inference_keeps_sdk_lease_until_http_response_closes(
+ tmp_path: Path, egress: CopilotEgress
+) -> None:
+ harness = Harness(tmp_path, egress)
+ harness.block_read = harness.block_close = True
+ operation = asyncio.create_task(collect(harness.stream(True)))
+ try:
+ while not harness.wires:
+ await asyncio.sleep(0)
+ wire = harness.wires[0]
+ await wire.read_entered.wait()
+ operation.cancel()
+ await wire.close_entered.wait()
+ disconnect = asyncio.create_task(harness.auth.disconnect())
+ cleanup = asyncio.create_task(harness.provider.cleanup())
+ await asyncio.sleep(0)
+ assert not disconnect.done() and not cleanup.done()
+ assert not harness.runtime.sessions[0].closed
+ wire.close_gate.set()
+ with pytest.raises(asyncio.CancelledError):
+ await operation
+ await disconnect
+ await cleanup
+ assert wire.closed and harness.runtime.sessions[0].closed
+ finally:
+ for wire in harness.wires:
+ wire.read_gate.set()
+ wire.close_gate.set()
+ await asyncio.gather(operation, return_exceptions=True)
+ await harness.provider.cleanup()
+ await harness.auth.close()
+
+
[email protected]("egress", list(CopilotEgress))
+async def test_http_failure_leaves_shared_account_available_and_releases_stream(
+ tmp_path: Path, egress: CopilotEgress
+) -> None:
+ harness = Harness(tmp_path, egress)
+ harness.statuses = [400]
+ try:
+ with pytest.raises(ExecutionFailure):
+ await collect(harness.stream(False))
+ assert harness.auth.is_connected()
+ await collect(harness.stream(False))
+ assert len(harness.seen) == 2
+ finally:
+ await harness.close()
+
+
+async def test_discovery_is_live_and_generation_cleanup_does_not_disconnect_account(
+ tmp_path: Path,
+) -> None:
+ harness = Harness(tmp_path, CopilotEgress.CHAT)
+ first = await harness.provider.list_model_infos()
+ harness.runtime.available = (
+ replace(
+ harness.runtime.available[0],
+ info=ProviderModelInfo(model_id="another-model"),
+ ),
+ )
+ second = await harness.provider.list_model_infos()
+ assert {model.model_id for model in first} == {harness.runtime.name}
+ assert {model.model_id for model in second} == {"another-model"}
+ await harness.provider.cleanup()
+ assert harness.auth.is_connected()
+ assert harness.runtime.close_calls == 0
+ await harness.auth.close()
+
+
+async def test_auto_is_never_resolved_by_an_inference_turn(tmp_path: Path) -> None:
+ harness = Harness(tmp_path, CopilotEgress.CHAT)
+ try:
+ with pytest.raises(InvalidRequestError, match="concrete"):
+ harness.provider.stream_responses(
+ OpenAIResponsesRequest(model="auto", input="hi")
+ )
+ assert not harness.seen and harness.runtime.session_calls == 0
+ finally:
+ await harness.close()
+
+
[email protected]("egress", list(CopilotEgress))
+async def test_repeated_cancellation_drains_physical_response_before_account_release(
+ tmp_path: Path, egress: CopilotEgress
+) -> None:
+ harness = Harness(tmp_path, egress)
+ harness.block_read = harness.block_close = True
+ operation = asyncio.create_task(collect(harness.stream(True)))
+ disconnect: asyncio.Task[object] | None = None
+ try:
+ while not harness.wires:
+ await asyncio.sleep(0)
+ wire = harness.wires[0]
+ await wire.read_entered.wait()
+ operation.cancel()
+ await wire.close_entered.wait()
+ operation.cancel()
+ disconnect = asyncio.create_task(harness.auth.disconnect())
+ for _ in range(8):
+ await asyncio.sleep(0)
+ assert not operation.done(), (
+ "cancellation returned before HTTP response cleanup"
+ )
+ assert not disconnect.done(), "account released while HTTP cleanup was pending"
+ wire.close_gate.set()
+ with pytest.raises(asyncio.CancelledError):
+ await operation
+ await disconnect
+ assert wire.closed
+ finally:
+ for wire in harness.wires:
+ wire.read_gate.set()
+ wire.close_gate.set()
+ await asyncio.gather(operation, return_exceptions=True)
+ if disconnect is not None:
+ await disconnect
+ await harness.provider.cleanup()
+ await harness.auth.close()
+
+
[email protected]("egress", list(CopilotEgress))
+async def test_rejected_credentials_are_replaced_by_the_refreshed_sdk_snapshot(
+ tmp_path: Path, egress: CopilotEgress
+) -> None:
+ harness = Harness(tmp_path, egress)
+ try:
+ # Prime the endpoint through the public account lease, without inference.
+ async with harness.auth.lease(harness.runtime.name):
+ pass
+ session = harness.runtime.sessions[0]
+ session.value = CopilotEndpoint(
+ egress,
+ HttpEndpoint(
+ "https://refreshed.invalid",
+ {"X-Session": "fresh-session"},
+ "fresh-secret",
+ ),
+ )
+ harness.statuses = [401]
+ await collect(harness.stream(True))
+ credential = (
+ "x-api-key" if egress is CopilotEgress.MESSAGES else "authorization"
+ )
+ first, second = harness.seen
+ assert first.url.host == "copilot.invalid"
+ assert "account-secret" in first.headers[credential]
+ assert second.url.host == "refreshed.invalid"
+ assert "fresh-secret" in second.headers[credential]
+ assert second.headers["x-session"] == "fresh-session"
+ assert "account-secret" not in str(second.headers)
+ finally:
+ await harness.close()
diff --git a/tests/providers/test_github_copilot_responses_identity.py b/tests/providers/test_github_copilot_responses_identity.py
new file mode 100644
index 00000000..82662012
--- /dev/null
+++ b/tests/providers/test_github_copilot_responses_identity.py
@@ -0,0 +1,510 @@
+"""Regression fixture from one authorized Copilot Responses capture.
+
+Opaque identifiers in the checked-in fixture are stable SHA256 labels. Their
+changes, output positions, call identities, event order, and synthetic arguments
+match the raw HTTP capture; no credentials or model reasoning are retained.
+"""
+
+import json
+from copy import deepcopy
+from pathlib import Path
+from typing import cast
+
+import httpx2
+import pytest
+
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.stream_contracts import (
+ assert_anthropic_stream_contract,
+ parse_sse_text,
+)
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.openai_responses import OpenAIResponsesRequest
+from free_claude_code.providers.github_copilot.types import CopilotEgress
+from tests.providers.test_github_copilot_provider import Harness, collect, responses_sse
+from tests.providers.test_openai_responses_transport import (
+ _completed_event,
+ _text_delta,
+)
+
+
+def _capture() -> list[JsonObject]:
+ path = Path(__file__).parent / "fixtures" / "copilot_responses_changing_ids.json"
+ return cast(
+ list[JsonObject], json.loads(path.read_text(encoding="utf-8"))["events"]
+ )
+
+
+def _item(event: JsonObject) -> JsonObject:
+ value = event["item"]
+ assert isinstance(value, dict)
+ return value
+
+
+def _response(event: JsonObject) -> JsonObject:
+ value = event["response"]
+ assert isinstance(value, dict)
+ return value
+
+
+def _output(event: JsonObject) -> list[JsonObject]:
+ output = _response(event)["output"]
+ assert isinstance(output, list)
+ assert all(isinstance(item, dict) for item in output)
+ return cast(list[JsonObject], output)
+
+
+def _input(responses: bool, model: str) -> MessagesRequest | OpenAIResponsesRequest:
+ schema = {
+ "type": "object",
+ "properties": {"value": {"type": "string"}},
+ "required": ["value"],
+ "additionalProperties": False,
+ }
+ if responses:
+ return OpenAIResponsesRequest.model_validate(
+ {
+ "model": model,
+ "input": "Call fcc_echo with value FCC_TOOL_OK.",
+ "tools": [
+ {"type": "function", "name": "fcc_echo", "parameters": schema}
+ ],
+ }
+ )
+ return MessagesRequest.model_validate(
+ {
+ "model": model,
+ "messages": [
+ {"role": "user", "content": "Call fcc_echo with value FCC_TOOL_OK."}
+ ],
+ "tools": [{"name": "fcc_echo", "input_schema": schema}],
+ }
+ )
+
+
+async def _run(
+ harness: Harness, request: MessagesRequest | OpenAIResponsesRequest
+) -> list[JsonObject]:
+ stream = (
+ harness.provider.stream_messages(request)
+ if isinstance(request, MessagesRequest)
+ else harness.provider.stream_responses(request)
+ )
+ raw = await collect(stream)
+ parsed = parse_sse_text(raw)
+ if isinstance(request, MessagesRequest):
+ assert_anthropic_stream_contract(parsed)
+ return [cast(JsonObject, event.data) for event in parsed]
+
+
+def _assert_native_identity(events: list[JsonObject]) -> list[JsonObject]:
+ responses = [_response(event) for event in events if "response" in event]
+ assert len({response["id"] for response in responses}) == 1
+ by_position: dict[int, str] = {}
+ for event in events:
+ position = event.get("output_index")
+ if not isinstance(position, int):
+ continue
+ current = _item(event)["id"] if "item" in event else event.get("item_id")
+ assert isinstance(current, str)
+ if position not in by_position:
+ by_position[position] = current
+ assert current == by_position[position]
+ output = _output(events[-1])
+ for position, item in enumerate(output):
+ assert item["id"] == by_position[position]
+ return output
+
+
[email protected]("responses", [False, True], ids=["messages", "responses"])
[email protected]("missing_delta_id", [False, True])
+async def test_captured_copilot_tool_identity_survives_stream_and_result_continuation(
+ tmp_path: Path, responses: bool, missing_delta_id: bool
+) -> None:
+ capture = _capture()
+ if missing_delta_id:
+ capture[5].pop("item_id")
+ call_id = _item(capture[2])["call_id"]
+ harness = Harness(tmp_path, CopilotEgress.RESPONSES)
+ harness.responses_content = responses_sse(*capture).encode()
+ try:
+ events = await _run(harness, _input(responses, harness.runtime.name))
+ if responses:
+ output = _assert_native_identity(events)
+ assert len(output) == 1
+ assert output[0] == {
+ **_output(capture[-1])[0],
+ "id": _item(capture[2])["id"],
+ }
+ followup = OpenAIResponsesRequest.model_validate(
+ {
+ "model": harness.runtime.name,
+ "input": [
+ *output,
+ {
+ "type": "function_call_output",
+ "call_id": call_id,
+ "output": "FCC_TOOL_OK",
+ },
+ ],
+ }
+ )
+ else:
+ starts = [
+ event["content_block"]
+ for event in events
+ if event["type"] == "content_block_start"
+ ]
+ assert starts == [
+ {"type": "tool_use", "id": call_id, "name": "fcc_echo", "input": {}}
+ ]
+ fragments = [
+ delta["partial_json"]
+ for event in events
+ if event["type"] == "content_block_delta"
+ and isinstance(delta := event.get("delta"), dict)
+ and delta.get("type") == "input_json_delta"
+ ]
+ assert all(isinstance(fragment, str) for fragment in fragments)
+ arguments = json.loads("".join(cast(list[str], fragments)))
+ assert arguments == {"value": "FCC_TOOL_OK"}
+ followup = MessagesRequest.model_validate(
+ {
+ "model": harness.runtime.name,
+ "messages": [
+ {"role": "user", "content": "Call fcc_echo."},
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": call_id,
+ "name": "fcc_echo",
+ "input": arguments,
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": call_id,
+ "content": "FCC_TOOL_OK",
+ }
+ ],
+ },
+ ],
+ }
+ )
+ harness.responses_content = responses_sse(
+ _text_delta("FCC_TOOL_OK"), _completed_event()
+ ).encode()
+ await _run(harness, followup)
+ body = json.loads(harness.seen[-1].content)
+ calls = [item for item in body["input"] if item.get("type") == "function_call"]
+ results = [
+ item for item in body["input"] if item.get("type") == "function_call_output"
+ ]
+ assert len(calls) == len(results) == 1
+ assert calls[0]["call_id"] == results[0]["call_id"] == call_id
+ assert calls[0]["name"] == "fcc_echo"
+ assert json.loads(calls[0]["arguments"]) == {"value": "FCC_TOOL_OK"}
+ assert results[0]["output"] == "FCC_TOOL_OK"
+ if responses:
+ assert calls == output
+ assert all(wire.closed for wire in harness.wires)
+ finally:
+ await harness.close()
+
+
[email protected]("responses", [False, True], ids=["messages", "responses"])
+async def test_copilot_done_only_tool_binds_identity_without_an_added_event(
+ tmp_path: Path, responses: bool
+) -> None:
+ capture = _capture()
+ capture = [
+ event
+ for event in capture
+ if event["type"]
+ in {"response.created", "response.output_item.done", "response.completed"}
+ ]
+ harness = Harness(tmp_path, CopilotEgress.RESPONSES)
+ harness.responses_content = responses_sse(*capture).encode()
+ try:
+ events = await _run(harness, _input(responses, harness.runtime.name))
+ if responses:
+ output = _assert_native_identity(events)
+ assert output[0]["id"] == _item(capture[1])["id"]
+ else:
+ starts = [
+ event["content_block"]
+ for event in events
+ if event["type"] == "content_block_start"
+ ]
+ assert len(starts) == 1
+ assert starts[0] == {
+ "type": "tool_use",
+ "id": _item(capture[1])["call_id"],
+ "name": "fcc_echo",
+ "input": {},
+ }
+ finally:
+ await harness.close()
+
+
[email protected]("responses", [False, True], ids=["messages", "responses"])
[email protected]("arguments_done_only", [False, True])
+async def test_copilot_argument_delta_without_item_metadata_fails_before_inventing_a_tool(
+ tmp_path: Path, responses: bool, arguments_done_only: bool
+) -> None:
+ capture = [
+ event for event in _capture() if event["type"] != "response.output_item.added"
+ ]
+ if arguments_done_only:
+ capture = [
+ event
+ for event in capture
+ if event["type"] != "response.function_call_arguments.delta"
+ ]
+ harness = Harness(tmp_path, CopilotEgress.RESPONSES)
+ harness.responses_content = responses_sse(*capture).encode()
+ emitted: list[JsonObject] = []
+ failure: ExecutionFailure | None = None
+ try:
+ request = _input(responses, harness.runtime.name)
+ stream = (
+ harness.provider.stream_messages(request)
+ if isinstance(request, MessagesRequest)
+ else harness.provider.stream_responses(request)
+ )
+ try:
+ async for chunk in stream:
+ emitted.extend(
+ cast(JsonObject, event.data) for event in parse_sse_text(chunk)
+ )
+ except ExecutionFailure as error:
+ failure = error
+ assert not any(
+ isinstance(block := event.get("content_block"), dict)
+ and block.get("type") == "tool_use"
+ for event in emitted
+ )
+ assert not any(
+ event["type"] == "response.function_call_arguments.delta"
+ for event in emitted
+ )
+ assert failure is not None or emitted[-1]["type"] == "response.failed"
+ assert all(wire.closed for wire in harness.wires)
+ finally:
+ await harness.close()
+
+
+async def test_copilot_interleaved_tools_use_output_positions_and_preserve_final_replay_payloads(
+ tmp_path: Path,
+) -> None:
+ capture = _capture()
+ first = deepcopy(_item(capture[2]))
+ second = {**first, "id": "opaque-second-added", "call_id": "call-second"}
+ reasoning = {"type": "reasoning", "id": "opaque-reasoning-added", "summary": []}
+ final_reasoning = {
+ **reasoning,
+ "id": "opaque-reasoning-final",
+ "summary": [{"type": "summary_text", "text": "synthetic fixture reasoning"}],
+ "encrypted_content": "synthetic-final-replay-content",
+ }
+ events: list[JsonObject] = [
+ capture[0],
+ capture[1],
+ capture[2],
+ {"type": "response.output_item.added", "output_index": 1, "item": second},
+ {"type": "response.output_item.added", "output_index": 2, "item": reasoning},
+ ]
+ for number, fragment in enumerate(('{"value":', '"FCC_TOOL_OK"}')):
+ events.extend(
+ {
+ "type": "response.function_call_arguments.delta",
+ "output_index": position,
+ "item_id": f"opaque-delta-{position}-{number}",
+ "delta": fragment,
+ }
+ for position in (0, 1)
+ )
+ for position, item in enumerate((first, second)):
+ events.append(
+ {
+ "type": "response.output_item.done",
+ "output_index": position,
+ "item": {
+ **item,
+ "id": f"opaque-done-{position}",
+ "status": "completed",
+ "arguments": '{"value":"FCC_TOOL_OK"}',
+ },
+ }
+ )
+ events.append(
+ {
+ "type": "response.output_item.done",
+ "output_index": 2,
+ "item": {**final_reasoning, "id": "opaque-reasoning-done"},
+ }
+ )
+ final_output: list[JsonObject] = [
+ {
+ **first,
+ "id": "opaque-final-0",
+ "status": "completed",
+ "arguments": '{"value":"FCC_TOOL_OK"}',
+ },
+ {
+ **second,
+ "id": "opaque-final-1",
+ "status": "completed",
+ "arguments": '{"value":"FCC_TOOL_OK"}',
+ },
+ final_reasoning,
+ ]
+ events.append(
+ {
+ "type": "response.completed",
+ "response": {**_response(capture[-1]), "output": final_output},
+ }
+ )
+ harness = Harness(tmp_path, CopilotEgress.RESPONSES)
+ harness.responses_content = responses_sse(*events).encode()
+ try:
+ received = await _run(harness, _input(True, harness.runtime.name))
+ output = _assert_native_identity(received)
+ assert output == [
+ {**final_output[0], "id": first["id"]},
+ {**final_output[1], "id": second["id"]},
+ {**final_reasoning, "id": reasoning["id"]},
+ ]
+ assert output[0]["call_id"] != output[1]["call_id"]
+ followup = OpenAIResponsesRequest.model_validate(
+ {
+ "model": harness.runtime.name,
+ "input": [
+ *output,
+ {
+ "type": "function_call_output",
+ "call_id": first["call_id"],
+ "output": "FCC_TOOL_OK",
+ },
+ {
+ "type": "function_call_output",
+ "call_id": second["call_id"],
+ "output": "FCC_TOOL_OK",
+ },
+ ],
+ }
+ )
+ harness.responses_content = responses_sse(
+ _text_delta("done"), _completed_event()
+ ).encode()
+ await _run(harness, followup)
+ body = json.loads(harness.seen[-1].content)
+ assert body["input"][:3] == output
+ finally:
+ await harness.close()
+
+
[email protected]("responses", [False, True])
[email protected]("field", ["call_id", "name", "type"])
[email protected]("missing", [False, True])
+async def test_copilot_rejects_incomplete_or_changed_tool_identity(
+ tmp_path: Path, responses: bool, field: str, missing: bool
+) -> None:
+ capture = _capture()
+ if missing:
+ _item(capture[2]).pop(field)
+ else:
+ _item(capture[11])[field] = "different"
+ _output(capture[-1])[0][field] = "different"
+ harness = Harness(tmp_path, CopilotEgress.RESPONSES)
+ harness.responses_content = responses_sse(*capture).encode()
+ failed = False
+ try:
+ try:
+ events = await _run(harness, _input(responses, harness.runtime.name))
+ failed = any(
+ event["type"] in {"error", "response.failed"} for event in events
+ )
+ except ExecutionFailure:
+ failed = True
+ assert failed, "Contradictory or incomplete tool identity must not succeed"
+ assert all(wire.closed for wire in harness.wires)
+ finally:
+ await harness.close()
+
+
+async def test_copilot_committed_failure_retains_public_response_and_item_identity(
+ tmp_path: Path,
+) -> None:
+ capture = _capture()
+ capture[3]["delta"] = " " * 70000 + str(capture[3]["delta"])
+ capture[-1]["type"] = "response.failed"
+ _response(capture[-1])["status"] = "failed"
+ _response(capture[-1])["error"] = {
+ "code": "server_error",
+ "message": "Synthetic upstream failure",
+ }
+ harness = Harness(tmp_path, CopilotEgress.RESPONSES)
+ harness.responses_content = responses_sse(*capture).encode()
+ try:
+ events = await _run(harness, _input(True, harness.runtime.name))
+ assert events[-1]["type"] == "response.failed"
+ output = _assert_native_identity(events)
+ assert output[0]["id"] == _item(capture[2])["id"]
+ assert len(harness.seen) == 1
+ assert all(wire.closed for wire in harness.wires)
+ finally:
+ await harness.close()
+
+
[email protected]("responses", [False, True])
+async def test_copilot_partial_failure_output_does_not_mask_authentication_refresh(
+ tmp_path: Path, responses: bool
+) -> None:
+ capture = _capture()
+ failed = deepcopy(capture[-1])
+ failed["type"] = "response.failed"
+ _response(failed).update(
+ status="failed",
+ error={"code": "invalid_api_key", "message": "expired"},
+ output=[{"id": "partial-final-tool", "type": "function_call"}],
+ )
+ recovered = deepcopy(capture)
+ _response(recovered[0])["id"] = "recovered-response"
+ _item(recovered[2])["id"] = "recovered-tool"
+
+ class RefreshHarness(Harness):
+ def openai(self, request: httpx2.Request) -> httpx2.Response:
+ if self.runtime.sessions[0].endpoint_calls > 1:
+ self.responses_content = responses_sse(*recovered).encode()
+ return super().openai(request)
+
+ harness = RefreshHarness(tmp_path, CopilotEgress.RESPONSES)
+ harness.responses_content = responses_sse(*capture[:3], failed).encode()
+ try:
+ events = await _run(harness, _input(responses, harness.runtime.name))
+ assert events[-1]["type"] == (
+ "response.completed" if responses else "message_stop"
+ )
+ assert harness.runtime.sessions[0].endpoint_calls == 2
+ assert len(harness.seen) == 2
+ if responses:
+ output = _assert_native_identity(events)
+ assert _response(events[-1])["id"] == "recovered-response"
+ assert output[0]["id"] == "recovered-tool"
+ finally:
+ await harness.close()
diff --git a/tests/providers/test_github_copilot_sdk.py b/tests/providers/test_github_copilot_sdk.py
new file mode 100644
index 00000000..2620c425
--- /dev/null
+++ b/tests/providers/test_github_copilot_sdk.py
@@ -0,0 +1,816 @@
+"""Pinned SDK account, endpoint metadata, inertness and lifecycle contracts."""
+
+import asyncio
+from datetime import UTC, datetime
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from copilot import CopilotClient, CopilotSession
+from copilot.rpc import Model, PermissionDecisionReject, ProviderEndpoint
+
+from free_claude_code.providers.github_copilot import sdk
+from free_claude_code.providers.github_copilot.types import (
+ CopilotEgress,
+ CopilotUnavailable,
+)
+
+
+def client(monkeypatch: pytest.MonkeyPatch) -> MagicMock:
+ client = MagicMock(spec=CopilotClient)
+ for name in ("start", "stop", "force_stop", "delete_session"):
+ setattr(client, name, AsyncMock())
+ client.get_status = AsyncMock(
+ return_value=SimpleNamespace(version=sdk.COPILOT_CLI_VERSION)
+ )
+ client.get_auth_status = AsyncMock(
+ return_value=SimpleNamespace(
+ isAuthenticated=True,
+ authType="user",
+ host="https://github.com",
+ login="octocat",
+ )
+ )
+ session = MagicMock(spec=CopilotSession)
+ session.disconnect = AsyncMock()
+ session.rpc = MagicMock()
+ client.create_session = AsyncMock(return_value=session)
+ client.rpc = MagicMock()
+ monkeypatch.setattr(sdk, "verified_cli_path", AsyncMock(return_value="copilot"))
+ monkeypatch.setattr(sdk, "CopilotClient", MagicMock(return_value=client))
+ return client
+
+
+def test_profile_environment_uses_native_account_without_token_or_byok_overrides() -> (
+ None
+):
+ assert sdk.profile_environment(
+ {
+ "Path": "bin",
+ "HOME": "home",
+ "COPILOT_HOME": "native",
+ "GH_HOST": "enterprise",
+ "gh_token": "secret",
+ "GITHUB_TOKEN": "secret",
+ "COPILOT_PROVIDER_FOO": "override",
+ "COPILOT_DISABLE_KEYTAR": "true",
+ }
+ ) == {
+ "Path": "bin",
+ "HOME": "home",
+ "COPILOT_HOME": "native",
+ "GH_HOST": "enterprise",
+ }
+
+
+async def test_native_profile_and_inert_session_contract(client: MagicMock) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ identity = await runtime.identity()
+ assert identity is not None and identity.display == "@octocat"
+ await runtime.session("claude-model")
+ args = client.create_session.call_args.kwargs
+ assert args["model"] == "claude-model"
+ assert args["available_tools"] == []
+ for flag in (
+ "enable_config_discovery",
+ "enable_file_hooks",
+ "enable_host_git_operations",
+ "enable_skills",
+ "enable_session_store",
+ "enable_session_telemetry",
+ ):
+ assert args[flag] is False
+ assert args["infinite_sessions"] == {"enabled": False}
+ assert args["memory"] == {"enabled": False}
+ directory = Path(args["working_directory"])
+ assert directory.is_dir()
+ await runtime.close()
+ client.delete_session.assert_awaited_once_with(args["session_id"])
+ assert not directory.exists()
+ client.stop.assert_awaited_once()
+
+
+async def test_disconnect_failure_still_deletes_owned_session(
+ client: MagicMock,
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ await runtime.session("model")
+ client.create_session.return_value.disconnect.side_effect = RuntimeError(
+ "detach failed"
+ )
+ await runtime.close()
+ client.delete_session.assert_awaited_once()
+ client.stop.assert_awaited_once()
+
+
+async def test_failed_deletion_retains_record_for_retry_after_stopping(
+ client: MagicMock,
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ await runtime.session("model")
+ client.delete_session.side_effect = [RuntimeError("delete failed"), None]
+ with pytest.raises(CopilotUnavailable, match="session record"):
+ await runtime.close()
+ client.stop.assert_awaited_once()
+ await runtime.close()
+ assert client.delete_session.await_count == 2
+ assert client.start.await_count == 2
+ assert client.stop.await_count == 2
+ await runtime.close()
+ assert client.delete_session.await_count == 2
+
+
[email protected]("creation_failed", [False, True])
+ "delete_error", [RuntimeError("no saved record"), TimeoutError()]
+)
+async def test_cleanup_finishes_when_owned_session_record_is_confirmed_absent(
+ client: MagicMock, creation_failed: bool, delete_error: Exception
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ if creation_failed:
+ client.create_session.side_effect = TimeoutError()
+ with pytest.raises(CopilotUnavailable):
+ await runtime.session("model")
+ else:
+ await runtime.session("model")
+ args = client.create_session.call_args.kwargs
+ directory = Path(args["working_directory"])
+ client.delete_session.side_effect = delete_error
+ client.get_session_metadata = AsyncMock(return_value=None)
+
+ await runtime.close()
+
+ client.get_session_metadata.assert_awaited_once_with(args["session_id"])
+ assert not directory.exists()
+ stopped = client.stop.await_count
+ await runtime.close()
+ assert client.stop.await_count == stopped
+
+
[email protected]("lookup_failed", [False, True])
+async def test_cleanup_retains_record_when_absence_cannot_be_verified(
+ client: MagicMock, lookup_failed: bool
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ await runtime.session("model")
+ args = client.create_session.call_args.kwargs
+ directory = Path(args["working_directory"])
+ client.delete_session.side_effect = [RuntimeError("delete failed"), None]
+ client.get_session_metadata = AsyncMock(
+ return_value=SimpleNamespace(session_id=args["session_id"]),
+ side_effect=TimeoutError() if lookup_failed else None,
+ )
+ with pytest.raises(CopilotUnavailable, match="session record"):
+ await runtime.close()
+ assert directory.exists()
+ await runtime.close()
+ assert not directory.exists()
+ assert client.delete_session.await_count == 2
+
+
+async def test_runtime_stop_allows_record_cleanup_without_retrying_stale_detach(
+ client: MagicMock,
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ session = await runtime.session("model")
+ directory = Path(client.create_session.call_args.kwargs["working_directory"])
+ client.create_session.return_value.disconnect.side_effect = RuntimeError(
+ "detach failed"
+ )
+ client.delete_session.side_effect = RuntimeError("record absent")
+ client.get_session_metadata = AsyncMock(return_value=None)
+ with pytest.raises(RuntimeError, match="record absent"):
+ await session.close()
+ with pytest.raises(CopilotUnavailable, match="session record"):
+ await runtime.close()
+ assert directory.exists()
+ detach_attempts = client.create_session.return_value.disconnect.await_count
+
+ await runtime.close()
+
+ assert not directory.exists()
+ assert client.create_session.return_value.disconnect.await_count == detach_attempts
+ with pytest.raises(CopilotUnavailable, match="closed"):
+ await session.endpoint()
+
+
+async def test_unknown_creation_record_is_cleaned_after_its_runtime_stops(
+ client: MagicMock,
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ client.create_session.side_effect = TimeoutError()
+ with pytest.raises(CopilotUnavailable):
+ await runtime.session("model")
+ pending_creation, record_exists = True, False
+
+ async def stop() -> None:
+ nonlocal pending_creation, record_exists
+ if pending_creation:
+ pending_creation = False
+ record_exists = True
+
+ async def delete(_session_id: str) -> None:
+ nonlocal record_exists
+ if not record_exists:
+ raise RuntimeError("record absent")
+ record_exists = False
+
+ async def metadata(_session_id: str) -> object:
+ return object() if record_exists else None
+
+ client.stop.side_effect = stop
+ client.delete_session.side_effect = delete
+ client.get_session_metadata = AsyncMock(side_effect=metadata)
+
+ await runtime.close()
+
+ assert not pending_creation
+ assert not record_exists
+
+
+async def test_cancelled_shutdown_drains_stop_before_cancellation(
+ client: MagicMock,
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ stopping, release = asyncio.Event(), asyncio.Event()
+
+ async def stop() -> None:
+ stopping.set()
+ await release.wait()
+
+ client.stop.side_effect = stop
+ task = asyncio.create_task(runtime.close())
+ await stopping.wait()
+ task.cancel()
+ await asyncio.sleep(0)
+ assert not task.done()
+ release.set()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ await runtime.close()
+ client.stop.assert_awaited_once()
+
+
+async def test_shutdown_force_stops_when_graceful_stop_fails(client: MagicMock) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ client.stop.side_effect = RuntimeError("stop failed")
+ await runtime.close()
+ client.force_stop.assert_awaited_once()
+
+
+async def test_failed_session_creation_retains_unknown_record_for_deletion(
+ client: MagicMock,
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ client.create_session.side_effect = TimeoutError()
+ with pytest.raises(CopilotUnavailable):
+ await runtime.session("model")
+ session_id = client.create_session.call_args.kwargs["session_id"]
+ await runtime.close()
+ client.delete_session.assert_awaited_once_with(session_id)
+
+
[email protected]("auth_type", ["env", "token", "api-key"])
+async def test_token_override_cannot_become_connected_account(
+ client: MagicMock, auth_type: str
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ client.get_auth_status.return_value.authType = auth_type
+ with pytest.raises(CopilotUnavailable, match="existing GitHub profile"):
+ await runtime.identity()
+ await runtime.close()
+
+
+ "family,wire,egress",
+ [
+ ("anthropic", None, CopilotEgress.MESSAGES),
+ ("openai", "responses", CopilotEgress.RESPONSES),
+ ("openai", "completions", CopilotEgress.CHAT),
+ ("openai", None, CopilotEgress.CHAT),
+ ],
+)
+def test_endpoint_uses_sdk_family_and_wire_metadata(
+ family: str, wire: str | None, egress: CopilotEgress
+) -> None:
+ endpoint = ProviderEndpoint.from_dict(
+ {
+ "type": family,
+ "wireApi": wire,
+ "baseUrl": "https://upstream.invalid",
+ "headers": {"X-Session": "secret"},
+ }
+ )
+ result = sdk._endpoint(endpoint, "model")
+ assert result.egress is egress
+ assert "secret" not in repr(result)
+
+
+ "field,value",
+ [
+ ("baseUrl", "http://upstream.invalid"),
+ ("baseUrl", "https://user:[email protected]"),
+ ("baseUrl", "https://upstream.invalid?token=x"),
+ ("transport", "websockets"),
+ ("type", "azure"),
+ ("headers", {"Invalid Header": "secret"}),
+ ("apiKey", "secret\nheader"),
+ ],
+)
+def test_endpoint_rejects_unsupported_or_unsafe_metadata(
+ field: str, value: object
+) -> None:
+ data = {
+ "type": "openai",
+ "baseUrl": "https://upstream.invalid",
+ "headers": {},
+ field: value,
+ }
+ with pytest.raises(CopilotUnavailable, match=r"unsupported|invalid"):
+ sdk._endpoint(ProviderEndpoint.from_dict(data), "model")
+
+
+async def test_discovery_is_uncached_and_filters_auto_and_disabled_models(
+ client: MagicMock,
+) -> None:
+ def model(name: str, policy: str) -> Model:
+ return Model.from_dict(
+ {
+ "id": name,
+ "name": name,
+ "capabilities": {
+ "supports": {
+ "vision": True,
+ "adaptive_thinking": "required",
+ "reasoningEffort": True,
+ },
+ "limits": {
+ "max_output_tokens": 42,
+ "max_context_window_tokens": 100,
+ },
+ },
+ "policy": {"state": policy},
+ "supportedReasoningEfforts": ["low", "high"],
+ }
+ )
+
+ client.rpc.models.list = AsyncMock(
+ return_value=SimpleNamespace(
+ models=[
+ model("Auto", "enabled"),
+ model("claude", "enabled"),
+ model("disabled", "disabled"),
+ ]
+ )
+ )
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ result = await runtime.models()
+ assert [item.info.model_id for item in result] == ["claude"]
+ assert result[0].messages.adaptive_thinking == "required"
+ assert result[0].info.max_output_tokens == 42
+ await runtime.models()
+ assert client.rpc.models.list.await_count == 2
+ await runtime.close()
+
+
+async def test_inert_constructor_preserves_native_profile_and_disables_overrides(
+ client: MagicMock, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setenv("COPILOT_HOME", "native-profile")
+ monkeypatch.setenv("GITHUB_TOKEN", "never-send-this")
+ monkeypatch.setenv("COPILOT_PROVIDER_OPENAI_API_KEY", "never-send-this")
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ constructor = sdk.CopilotClient
+ assert isinstance(constructor, MagicMock)
+ options = constructor.call_args.kwargs
+ assert options["mode"] == "copilot-cli"
+ assert options["use_logged_in_user"] is True
+ assert options["log_level"] == "error"
+ assert options["connection"] == sdk.RuntimeConnection.for_stdio(
+ path="copilot", args=("--disable-builtin-mcps",)
+ )
+ assert options["env"]["COPILOT_HOME"] == "native-profile"
+ assert options["env"]["COPILOT_ALLOW_GET_PROVIDER_ENDPOINT"] == "true"
+ assert "never-send-this" not in options["env"].values()
+ assert Path(options["working_directory"]).is_dir()
+ assert "base_directory" not in options
+ assert "github_token" not in options
+ await runtime.session("model")
+ args = client.create_session.call_args.kwargs
+ for flag in (
+ "enable_on_demand_instruction_discovery",
+ "request_extensions",
+ ):
+ assert args[flag] is False
+ for flag in (
+ "skip_custom_instructions",
+ "custom_agents_local_only",
+ "skip_embedding_retrieval",
+ ):
+ assert args[flag] is True
+ assert args["embedding_cache_storage"] == "in-memory"
+ assert args["mcp_oauth_token_storage"] == "in-memory"
+ assert args["capi"] == {"enable_web_socket_responses": False}
+ assert args["included_builtin_skills"] == []
+ decision = args["on_permission_request"](MagicMock(), MagicMock())
+ assert isinstance(decision, PermissionDecisionReject)
+ client.create_session.return_value.send.assert_not_called()
+ await runtime.close()
+
+
+async def test_cleanup_reconnect_failure_stops_partial_runtime_and_retains_deletion(
+ client: MagicMock,
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ await runtime.session("model")
+ client.delete_session.side_effect = [RuntimeError("delete failed"), None]
+ with pytest.raises(CopilotUnavailable, match="session record"):
+ await runtime.close()
+ client.start.side_effect = [RuntimeError("partial restart"), None]
+ with pytest.raises(CopilotUnavailable, match="reconnect"):
+ await runtime.close()
+ assert client.stop.await_count == 2
+ assert client.delete_session.await_count == 1
+ await runtime.close()
+ assert client.stop.await_count == 3
+ assert client.delete_session.await_count == 2
+
+
+async def test_failed_stop_and_force_stop_preserve_runtime_for_retry(
+ client: MagicMock,
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ client.stop.side_effect = [RuntimeError("stop failed"), None]
+ client.force_stop.side_effect = RuntimeError("force stop failed")
+ with pytest.raises(CopilotUnavailable, match="Could not stop"):
+ await runtime.close()
+ await runtime.close()
+ assert client.start.await_count == 1
+ assert client.stop.await_count == 2
+ assert client.force_stop.await_count == 1
+
+
+async def test_cancelled_start_drains_partial_runtime_before_returning(
+ client: MagicMock,
+) -> None:
+ starting, stopping, release = asyncio.Event(), asyncio.Event(), asyncio.Event()
+
+ async def start() -> None:
+ starting.set()
+ await asyncio.Event().wait()
+
+ async def stop() -> None:
+ stopping.set()
+ await release.wait()
+
+ client.start.side_effect = start
+ client.stop.side_effect = stop
+ runtime = sdk.SdkRuntime()
+ task = asyncio.create_task(runtime.start())
+ await starting.wait()
+ task.cancel()
+ await stopping.wait()
+ task.cancel()
+ await asyncio.sleep(0)
+ assert not task.done()
+ release.set()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ await runtime.close()
+ client.stop.assert_awaited_once()
+
+
+async def test_cancelled_creation_retains_pending_record_until_runtime_close(
+ client: MagicMock,
+) -> None:
+ creating = asyncio.Event()
+
+ async def create(**_kwargs: object) -> None:
+ creating.set()
+ await asyncio.Event().wait()
+
+ client.create_session.side_effect = create
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ task = asyncio.create_task(runtime.session("model"))
+ await creating.wait()
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ await runtime.close()
+ client.delete_session.assert_awaited_once_with(
+ client.create_session.call_args.kwargs["session_id"]
+ )
+
+
+async def test_cancelled_session_close_waits_for_record_deletion(
+ client: MagicMock,
+) -> None:
+ deleting, release = asyncio.Event(), asyncio.Event()
+
+ async def delete(_session_id: str) -> None:
+ deleting.set()
+ await release.wait()
+
+ client.delete_session.side_effect = delete
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ session = await runtime.session("model")
+ task = asyncio.create_task(session.close())
+ await deleting.wait()
+ task.cancel()
+ await asyncio.sleep(0)
+ assert not task.done()
+ release.set()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ await runtime.close()
+ client.delete_session.assert_awaited_once()
+
+
+async def test_session_endpoint_refresh_returns_fresh_bound_immutable_snapshot(
+ client: MagicMock,
+) -> None:
+ original = ProviderEndpoint.from_dict(
+ {
+ "type": "anthropic",
+ "baseUrl": "https://upstream.invalid/",
+ "headers": {"X-Session": "old", "x-other": "original"},
+ "sessionToken": {
+ "header": "x-session",
+ "token": "first-secret",
+ "model": "model",
+ "expiresAt": "2026-09-04T20:00:00+02:00",
+ },
+ }
+ )
+ rotated = ProviderEndpoint.from_dict(
+ {
+ "type": "anthropic",
+ "baseUrl": "https://other-upstream.invalid",
+ "headers": {},
+ "sessionToken": {"header": "X-Session", "token": "second-secret"},
+ }
+ )
+ resolve = AsyncMock(side_effect=[original, rotated])
+ client.create_session.return_value.rpc.provider.get_endpoint = resolve
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ session = await runtime.session("model")
+ first = await session.endpoint()
+ second = await session.endpoint()
+ assert first.http.base_url == "https://upstream.invalid"
+ assert first.http.headers == {"x-other": "original", "x-session": "first-secret"}
+ assert first.expires_at == datetime(2026, 9, 4, 18, tzinfo=UTC).timestamp()
+ assert second.http.headers == {"x-session": "second-secret"}
+ assert second.expires_at is None
+ original.headers["x-other"] = "changed-after-snapshot"
+ assert first.http.headers["x-other"] == "original"
+ assert "secret" not in repr(first)
+ assert "secret" not in repr(first.http)
+ assert resolve.await_count == 2
+ for call in resolve.await_args_list:
+ assert call.args[0].model_id == "model"
+ assert call.kwargs["timeout"] == sdk.SDK_RPC_TIMEOUT
+ await runtime.close()
+ with pytest.raises(CopilotUnavailable, match="closed"):
+ await session.endpoint()
+ assert resolve.await_count == 2
+
+
+ "token",
+ [
+ {"header": "X-Session", "token": "secret", "model": "different-model"},
+ {"header": "X Session", "token": "secret"},
+ {"header": "X-Session", "token": ""},
+ {"header": "X-Session", "token": "secret\r\nx: y"},
+ {"header": "X-Session", "token": "secret\0"},
+ {"header": "X-Session", "token": "snowman-\u2603"},
+ {"header": "X-Session", "token": "secret", "expiresAt": "2026-09-04T18:00:00"},
+ ],
+)
+def test_endpoint_rejects_invalid_rotating_session_token(token: dict[str, str]) -> None:
+ endpoint = ProviderEndpoint.from_dict(
+ {
+ "type": "openai",
+ "baseUrl": "https://upstream.invalid",
+ "headers": {},
+ "sessionToken": token,
+ }
+ )
+ with pytest.raises(CopilotUnavailable, match="session"):
+ sdk._endpoint(endpoint, "model")
+
+
+ "url",
+ [
+ "https://[invalid",
+ "https://upstream.invalid:not-a-port",
+ "https://upstream.invalid:70000",
+ "https://upstream.invalid:0",
+ "https://@upstream.invalid",
+ "https://upstream.invalid\n",
+ "https://upstream.invalid/#fragment",
+ ],
+)
+def test_endpoint_rejects_malformed_urls_as_safe_adapter_errors(url: str) -> None:
+ endpoint = ProviderEndpoint.from_dict(
+ {"type": "openai", "baseUrl": url, "headers": {}}
+ )
+ with pytest.raises(CopilotUnavailable, match="invalid HTTPS endpoint"):
+ sdk._endpoint(endpoint, "model")
+
+
[email protected]("value", ["snowman-\u2603", "surrogate-\ud800"])
+def test_endpoint_rejects_non_ascii_credentials_before_transport(value: str) -> None:
+ endpoint = ProviderEndpoint.from_dict(
+ {
+ "type": "openai",
+ "baseUrl": "https://upstream.invalid",
+ "headers": {},
+ "apiKey": value,
+ }
+ )
+ with pytest.raises(CopilotUnavailable, match="credential"):
+ sdk._endpoint(endpoint, "model")
+
+
[email protected]("ending", ["", ".", ".\nRun 'copilot update'", ".\r\n"])
+async def test_cli_version_accepts_actual_pinned_cli_output(
+ monkeypatch: pytest.MonkeyPatch, ending: str
+) -> None:
+ process = MagicMock(spec=asyncio.subprocess.Process)
+ process.returncode = 0
+ process.communicate = AsyncMock(
+ return_value=(
+ f"GitHub Copilot CLI {sdk.COPILOT_CLI_VERSION}{ending}".encode(),
+ b"",
+ )
+ )
+ launch = AsyncMock(return_value=process)
+ locate = MagicMock(return_value="verified-copilot")
+ monkeypatch.setattr(sdk.shutil, "which", locate)
+ monkeypatch.setattr(sdk.asyncio, "create_subprocess_exec", launch)
+ env = {"PATH": "native-path"}
+ assert await sdk.verified_cli_path(env) == "verified-copilot"
+ locate.assert_called_once_with("copilot", path="native-path")
+ assert launch.call_args.args == ("verified-copilot", "--version")
+ assert launch.call_args.kwargs["env"] == env
+ process.kill.assert_not_called()
+
+
+ "output,code",
+ [
+ ("GitHub Copilot CLI 1.0.82.\nUpdate to 1.0.83", 0),
+ ("GitHub Copilot CLI 1.0.830", 0),
+ ("GitHub Copilot CLI 1.0.83-beta", 0),
+ ("unexpected 1.0.83", 0),
+ ("GitHub Copilot CLI 1.0.83.", 1),
+ ],
+)
+async def test_cli_version_rejects_unpinned_or_failed_cli_output(
+ monkeypatch: pytest.MonkeyPatch, output: str, code: int
+) -> None:
+ process = MagicMock(spec=asyncio.subprocess.Process)
+ process.returncode = code
+ process.communicate = AsyncMock(
+ return_value=(output.encode(), b"private diagnostic")
+ )
+ monkeypatch.setattr(sdk.shutil, "which", MagicMock(return_value="copilot"))
+ monkeypatch.setattr(
+ sdk.asyncio, "create_subprocess_exec", AsyncMock(return_value=process)
+ )
+ with pytest.raises(
+ CopilotUnavailable, match="requires GitHub Copilot CLI"
+ ) as error:
+ await sdk.verified_cli_path({})
+ assert "private diagnostic" not in str(error.value)
+
+
+async def test_missing_cli_does_not_spawn_process(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ launch = AsyncMock()
+ monkeypatch.setattr(sdk.shutil, "which", MagicMock(return_value=None))
+ monkeypatch.setattr(sdk.asyncio, "create_subprocess_exec", launch)
+ with pytest.raises(CopilotUnavailable, match="Install GitHub Copilot CLI"):
+ await sdk.verified_cli_path({})
+ launch.assert_not_awaited()
+
+
+async def test_cancelled_cli_version_probe_drains_process_under_repeated_cancellation(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ started, reaping, release = asyncio.Event(), asyncio.Event(), asyncio.Event()
+ process = MagicMock(spec=asyncio.subprocess.Process)
+ process.returncode = None
+
+ async def communicate() -> tuple[bytes, bytes]:
+ if not started.is_set():
+ started.set()
+ await asyncio.Event().wait()
+ reaping.set()
+ await release.wait()
+ process.returncode = -1
+ return b"", b""
+
+ process.communicate = AsyncMock(side_effect=communicate)
+ monkeypatch.setattr(sdk.shutil, "which", MagicMock(return_value="copilot"))
+ monkeypatch.setattr(
+ sdk.asyncio, "create_subprocess_exec", AsyncMock(return_value=process)
+ )
+ task = asyncio.create_task(sdk.verified_cli_path({}))
+ await started.wait()
+ task.cancel()
+ await reaping.wait()
+ task.cancel()
+ await asyncio.sleep(0)
+ assert not task.done()
+ process.kill.assert_called_once()
+ release.set()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert process.returncode == -1
+
+
+async def test_runtime_version_mismatch_stops_runtime_and_never_creates_session(
+ client: MagicMock,
+) -> None:
+ client.get_status.return_value.version = "unverified-version"
+ runtime = sdk.SdkRuntime()
+ with pytest.raises(CopilotUnavailable, match="version changed"):
+ await runtime.start()
+ client.stop.assert_awaited_once()
+ client.create_session.assert_not_awaited()
+ await runtime.close()
+ client.stop.assert_awaited_once()
+
+
+async def test_native_signed_out_profile_is_distinct_from_invalid_auth(
+ client: MagicMock,
+) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ client.get_auth_status.return_value.isAuthenticated = False
+ assert await runtime.identity() is None
+ await runtime.close()
+
+
+async def test_gh_cli_enterprise_profile_is_supported(client: MagicMock) -> None:
+ runtime = sdk.SdkRuntime()
+ await runtime.start()
+ client.get_auth_status.return_value.authType = "gh-cli"
+ client.get_auth_status.return_value.host = "HTTPS://GitHub.Enterprise.Example"
+ identity = await runtime.identity()
+ assert identity is not None
+ assert identity.host == "github.enterprise.example"
+ assert "octocat" in identity.display
+ await runtime.close()
diff --git a/tests/providers/test_messages_request_policy.py b/tests/providers/test_messages_request_policy.py
new file mode 100644
index 00000000..5914f0d9
--- /dev/null
+++ b/tests/providers/test_messages_request_policy.py
@@ -0,0 +1,212 @@
+"""Native controls stay metadata-driven and preserve exact caller budgets."""
+
+import pytest
+
+from free_claude_code.core.anthropic.models import ThinkingConfig
+from free_claude_code.core.anthropic.native import NativeMessagesError
+from free_claude_code.core.reasoning import (
+ ReasoningControl,
+ ReasoningEffort,
+ ReasoningPolicy,
+)
+from free_claude_code.providers.anthropic_messages.request_policy import (
+ MessagesModelCapabilities,
+ resolve_messages_options,
+)
+
+
+def test_unknown_defaults_do_not_invent_thinking_or_output_cap() -> None:
+ options = resolve_messages_options(
+ model="anything", max_tokens=None, reasoning=ReasoningPolicy()
+ )
+ assert options.max_tokens == 8192
+ assert options.thinking is None
+ assert options.output_effort is None
+
+
[email protected]("limit", [0, -1, True])
+def test_invalid_output_limit_rejected(limit: int) -> None:
+ with pytest.raises(NativeMessagesError, match="positive integer"):
+ resolve_messages_options(
+ model="m", max_tokens=limit, reasoning=ReasoningPolicy()
+ )
+
+
+def test_output_cap_clamps_generation_but_never_an_exact_thinking_budget() -> None:
+ caps = MessagesModelCapabilities(
+ max_output_tokens=2048, adaptive_thinking="optional"
+ )
+ with pytest.raises(NativeMessagesError, match="below max_tokens"):
+ resolve_messages_options(
+ model="m",
+ max_tokens=4096,
+ capabilities=caps,
+ reasoning=ReasoningPolicy.on(budget_tokens=2048),
+ )
+ options = resolve_messages_options(
+ model="m",
+ max_tokens=4096,
+ capabilities=caps,
+ reasoning=ReasoningPolicy.on(budget_tokens=1024),
+ )
+ assert options.max_tokens == 2048
+ assert options.thinking == {"type": "enabled", "budget_tokens": 1024}
+
+
+def test_adaptive_only_rejects_exact_budget_but_allows_off() -> None:
+ caps = MessagesModelCapabilities(adaptive_thinking="required")
+ with pytest.raises(NativeMessagesError, match="requires adaptive"):
+ resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ capabilities=caps,
+ reasoning=ReasoningPolicy.on(budget_tokens=1024),
+ )
+ options = resolve_messages_options(
+ model="m", max_tokens=None, capabilities=caps, reasoning=ReasoningPolicy.off()
+ )
+ assert options.thinking == {"type": "disabled"}
+
+
+def test_explicit_native_mode_works_without_model_heuristics() -> None:
+ options = resolve_messages_options(
+ model="unfamiliar-name",
+ max_tokens=4096,
+ reasoning=ReasoningPolicy.on(budget_tokens=1536),
+ thinking=ThinkingConfig(type="enabled", budget_tokens=1536, display="omitted"),
+ )
+ assert options.thinking == {
+ "type": "enabled",
+ "budget_tokens": 1536,
+ "display": "omitted",
+ }
+ options = resolve_messages_options(
+ model="another-name",
+ max_tokens=4096,
+ reasoning=ReasoningPolicy.on(),
+ thinking=ThinkingConfig(type="adaptive"),
+ )
+ assert options.thinking == {"type": "adaptive"}
+
+
+def test_unknown_mode_cannot_be_guessed_from_effort_support() -> None:
+ with pytest.raises(NativeMessagesError, match="thinking mode"):
+ resolve_messages_options(
+ model="claude-something",
+ max_tokens=None,
+ capabilities=MessagesModelCapabilities(supports_output_effort=True),
+ reasoning=ReasoningPolicy.on(effort=ReasoningEffort.HIGH),
+ )
+
+
+def test_advertised_effort_without_forced_thinking_works() -> None:
+ options = resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ capabilities=MessagesModelCapabilities(supported_efforts=("low", "high")),
+ reasoning=ReasoningPolicy(effort=ReasoningEffort.MINIMAL),
+ )
+ assert options.output_effort == "low"
+ assert options.thinking is None
+ with pytest.raises(NativeMessagesError, match="does not support effort"):
+ resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ capabilities=MessagesModelCapabilities(supported_efforts=("low", "high")),
+ reasoning=ReasoningPolicy(effort=ReasoningEffort.MAX),
+ )
+
+
+def test_manual_effort_uses_budget_and_minimum() -> None:
+ options = resolve_messages_options(
+ model="m",
+ max_tokens=1500,
+ capabilities=MessagesModelCapabilities(
+ adaptive_thinking="unsupported", supports_output_effort=False
+ ),
+ reasoning=ReasoningPolicy.on(effort=ReasoningEffort.LOW),
+ )
+ assert options.thinking == {"type": "enabled", "budget_tokens": 1024}
+ assert options.output_effort is None
+
+
[email protected]("raw", ["bogus", 1, {"mode": "high"}])
+def test_client_on_cannot_hide_invalid_output_effort(raw: object) -> None:
+ with pytest.raises(NativeMessagesError, match="client output effort"):
+ resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ output_effort=raw,
+ reasoning=ReasoningPolicy.on(budget_tokens=1536),
+ thinking=ThinkingConfig(type="enabled", budget_tokens=1536),
+ )
+
+
+def test_off_overrides_native_hint_without_dropping_independent_effort() -> None:
+ options = resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ reasoning=ReasoningPolicy(
+ control=ReasoningControl.OFF, effort=ReasoningEffort.LOW
+ ),
+ capabilities=MessagesModelCapabilities(supported_efforts=("low",)),
+ thinking=ThinkingConfig(type="enabled", budget_tokens=1024, display="omitted"),
+ )
+ assert options.thinking == {"type": "disabled"}
+ assert options.output_effort == "low"
+
+
+def test_unknown_thinking_options_and_adaptive_budget_rejected() -> None:
+ with pytest.raises(NativeMessagesError, match="Unsupported native thinking option"):
+ resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ reasoning=ReasoningPolicy(),
+ thinking=ThinkingConfig.model_validate({"type": "adaptive", "mystery": 1}),
+ )
+ with pytest.raises(NativeMessagesError, match="exact token budget"):
+ resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ reasoning=ReasoningPolicy(),
+ thinking=ThinkingConfig(type="adaptive", budget_tokens=1024),
+ )
+
+
+def test_configured_off_does_not_resurrect_raw_client_effort() -> None:
+ options = resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ reasoning=ReasoningPolicy.off(),
+ output_effort="high",
+ capabilities=MessagesModelCapabilities(supported_efforts=("high",)),
+ )
+ assert options.thinking == {"type": "disabled"}
+ assert options.output_effort is None
+
+
[email protected]("effort", ["minimal", "bogus"])
+def test_effort_support_boolean_does_not_authorize_unknown_native_values(
+ effort: str,
+) -> None:
+ with pytest.raises(NativeMessagesError, match="effort"):
+ resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ reasoning=ReasoningPolicy(),
+ output_effort=effort,
+ capabilities=MessagesModelCapabilities(supports_output_effort=True),
+ )
+
+
+def test_manual_minimal_effort_is_represented_only_by_numeric_budget() -> None:
+ options = resolve_messages_options(
+ model="m",
+ max_tokens=None,
+ reasoning=ReasoningPolicy.on(effort=ReasoningEffort.MINIMAL),
+ capabilities=MessagesModelCapabilities(
+ adaptive_thinking="unsupported", supports_output_effort=False
+ ),
+ )
+ assert options.thinking == {"type": "enabled", "budget_tokens": 1024}
+ assert options.output_effort is None
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index be49694b..78c6f9d9 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -44,6 +44,7 @@ from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.cloudflare import CloudflareProvider
from free_claude_code.providers.deepseek import DeepSeekProvider
from free_claude_code.providers.gemini import GeminiProvider
+from free_claude_code.providers.github_copilot.provider import GitHubCopilotProvider
from free_claude_code.providers.groq import GroqProvider
from free_claude_code.providers.kilo import KiloProvider
from free_claude_code.providers.lmstudio import LMStudioProvider
@@ -847,6 +848,7 @@ def test_create_provider_instantiates_each_builtin():
cases = {
"nvidia_nim": NvidiaNimProvider,
"openai": OpenAICodexProvider,
+ "github_copilot": GitHubCopilotProvider,
"cline_pass": OpenAIChatProvider,
"xai": OpenAIChatProvider,
"qwencloud": OpenAIChatProvider,
@@ -902,11 +904,17 @@ def test_create_provider_instantiates_each_builtin():
config,
auth=auth,
admission=admission,
- )
+ ),
+ "github_copilot": lambda config, _settings, admission: GitHubCopilotProvider(
+ config,
+ auth=auth,
+ admission=admission,
+ ),
}
with (
patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"),
+ patch("free_claude_code.providers.github_copilot.provider.AsyncOpenAI"),
patch("httpx.AsyncClient"),
patch(
"free_claude_code.providers.runtime.factory.ProviderAdmissionController",
diff --git a/uv.lock b/uv.lock
index 543db0e8..8e871bcb 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,13 +598,14 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.21.1"
+version = "5.22.1"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },
{ name = "anyio" },
{ name = "discord-py" },
{ name = "fastapi", extra = ["standard"] },
+ { name = "github-copilot-sdk" },
{ name = "google-auth", extra = ["requests"] },
{ name = "httpx", extra = ["socks"] },
{ name = "httpx2", extra = ["socks"] },
@@ -653,6 +654,7 @@ requires-dist = [
{ name = "anyio", specifier = ">=4.12.1" },
{ name = "discord-py", specifier = ">=2.7.1" },
{ name = "fastapi", extras = ["standard"], specifier = ">=0.141.1" },
+ { name = "github-copilot-sdk", specifier = "==1.0.13" },
{ name = "google-auth", extras = ["requests"], specifier = ">=2.56.3" },
{ name = "grpcio", marker = "extra == 'voice'", specifier = ">=1.83.0" },
{ name = "grpcio-tools", marker = "extra == 'voice'", specifier = ">=1.81.1" },
@@ -738,6 +740,19 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/e6/ab/fb21f4c939bb440104cc2b396d3be1d9b7a9fd3c6c2a53d98c45b3d7c954/fsspec-2026.2.0-py3-none-any.whl", hash = "sha256:98de475b5cb3bd66bedd5c4679e87b4fdfe1a3bf4d707b151b3c07e58c9a2437", size = 202505, upload-time = "2026-02-05T21:50:51.819Z" },
]
+[[package]]
+name = "github-copilot-sdk"
+version = "1.0.13"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "httpx" },
+ { name = "pydantic" },
+ { name = "python-dateutil" },
+]
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2d/6d/4f2e3dddc576ff49739317adba6f9b8c35e93b835ece923e46f1b7fa6028/github_copilot_sdk-1.0.13-py3-none-any.whl", hash = "sha256:941dd5b55cf32ba55c73c651052a4a52b259b470c68bf6a6ac3d240c235402c9", size = 588198, upload-time = "2026-09-04T21:31:02.063Z" },
+]
+
[[package]]
name = "google-auth"
version = "2.56.3"
@@ -1985,6 +2000,18 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/ca/31/d4e37e9e550c2b92a9cbc2e4d0b7420a27224968580b5a447f420847c975/pytest_xdist-3.8.0-py3-none-any.whl", hash = "sha256:202ca578cfeb7370784a8c33d6d05bc6e13b4f25b5053c30a152269fd10f0b88", size = 46396, upload-time = "2025-07-01T13:30:56.632Z" },
]
+[[package]]
+name = "python-dateutil"
+version = "2.9.0.post0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "six" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" },
+]
+
[[package]]
name = "python-dotenv"
version = "1.2.3"