pi-ai-python 1.3.0__py3-none-any.whl

pi_ai/providers/github_copilot.py

@@ -0,0 +1,46 @@
+"""GitHub Copilot provider."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ..api.registry import anthropic_messages_api, openai_completions_api, openai_responses_api
+from ..auth.helpers import env_api_key_auth, lazy_oauth
+from ..auth.oauth.load import load_github_copilot_oauth
+from ..auth.types import Credential, ProviderAuth
+from ..models import Provider, create_provider
+from ..types import Model
+from .catalog import catalog_models
+
+__all__ = ["github_copilot_provider"]
+
+
+def _filter_models(models: Sequence[Model], credential: Credential | None) -> Sequence[Model]:
+    # OAuth credentials record the models the Copilot plan enables.
+    if credential is None or credential.get("type") != "oauth":
+        return models
+    available_model_ids = credential.get("availableModelIds")
+    if not isinstance(available_model_ids, list) or not all(isinstance(item, str) for item in available_model_ids):
+        return models
+    available = set(available_model_ids)
+    return [model for model in models if model.id in available]
+
+
+def github_copilot_provider() -> Provider:
+    """GitHub Copilot: ``COPILOT_GITHUB_TOKEN`` or a GitHub Copilot login (Anthropic/OpenAI APIs)."""
+    return create_provider(
+        id="github-copilot",
+        name="GitHub Copilot",
+        base_url="https://api.individual.githubcopilot.com",
+        auth=ProviderAuth(
+            api_key=env_api_key_auth("GitHub Copilot token", ["COPILOT_GITHUB_TOKEN"]),
+            oauth=lazy_oauth("GitHub Copilot", load_github_copilot_oauth, is_subscription=True),
+        ),
+        models=lambda: catalog_models("github-copilot"),
+        filter_models=_filter_models,
+        api={
+            "anthropic-messages": anthropic_messages_api(),
+            "openai-completions": openai_completions_api(),
+            "openai-responses": openai_responses_api(),
+        },
+    )

pi_ai/providers/google.py

@@ -0,0 +1,23 @@
+"""Google provider."""
+
+from __future__ import annotations
+
+from ..api.registry import google_generative_ai_api
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["google_provider"]
+
+
+def google_provider() -> Provider:
+    """Google (Gemini API), authenticated with ``GEMINI_API_KEY``."""
+    return create_provider(
+        id="google",
+        name="Google",
+        base_url="https://generativelanguage.googleapis.com/v1beta",
+        auth=ProviderAuth(api_key=env_api_key_auth("Gemini API key", ["GEMINI_API_KEY"])),
+        models=lambda: catalog_models("google"),
+        api=google_generative_ai_api(),
+    )

pi_ai/providers/google_vertex.py

@@ -0,0 +1,131 @@
+"""Google Vertex AI provider."""
+
+from __future__ import annotations
+
+from ..abort import AbortSignal
+from ..api.registry import google_vertex_api
+from ..auth.types import (
+    ApiKeyAuth,
+    AuthContext,
+    AuthEvent,
+    AuthInfoLink,
+    AuthPrompt,
+    AuthResult,
+    AuthSelectOption,
+    Credential,
+    ModelAuth,
+    ProviderAuth,
+    ProviderAuthInteraction,
+)
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["google_vertex_provider", "vertex_auth", "VERTEX_ADC_PATH"]
+
+VERTEX_ADC_PATH = "~/.config/gcloud/application_default_credentials.json"
+
+
+async def _login(interaction: ProviderAuthInteraction) -> Credential:
+    interaction.signal.throw_if_aborted()
+    method = await interaction.prompt(
+        AuthPrompt(
+            type="select",
+            message="Select Google Vertex AI authentication method:",
+            options=[
+                AuthSelectOption(id="api-key", label="Google Cloud API key"),
+                AuthSelectOption(id="adc", label="Application Default Credentials"),
+                AuthSelectOption(id="service-account", label="Service account credentials file"),
+            ],
+        )
+    )
+    interaction.signal.throw_if_aborted()
+    if method == "api-key":
+        return {
+            "type": "api_key",
+            "key": await interaction.prompt(AuthPrompt(type="secret", message="Enter Google Cloud API key")),
+        }
+    if method not in ("adc", "service-account"):
+        raise ValueError(f"Unknown Google Vertex AI auth method: {method}")
+    interaction.notify(
+        AuthEvent(
+            type="info",
+            message=(
+                "Run `gcloud auth application-default login`, then provide the project and location."
+                if method == "adc"
+                else "Provide a service account credentials file, project, and location."
+            ),
+            links=[
+                AuthInfoLink(
+                    label="Application Default Credentials",
+                    url="https://cloud.google.com/docs/authentication/provide-credentials-adc",
+                )
+            ],
+        )
+    )
+    project = await interaction.prompt(AuthPrompt(type="text", message="Enter Google Cloud project ID"))
+    location = await interaction.prompt(AuthPrompt(type="text", message="Enter Google Cloud location"))
+    credentials_path = (
+        await interaction.prompt(AuthPrompt(type="text", message="Enter service account credentials file path"))
+        if method == "service-account"
+        else None
+    )
+    env = {"GOOGLE_CLOUD_PROJECT": project, "GOOGLE_CLOUD_LOCATION": location}
+    if credentials_path:
+        env["GOOGLE_APPLICATION_CREDENTIALS"] = credentials_path
+    return {"type": "api_key", "env": env}
+
+
+async def _resolve(*, ctx: AuthContext, credential: Credential | None, signal: AbortSignal) -> AuthResult | None:
+    async def env(name: str) -> str | None:
+        signal.throw_if_aborted()
+        value = await ctx.env(name)
+        signal.throw_if_aborted()
+        return value
+
+    stored_key = credential.get("key") if credential else None
+    key = stored_key if stored_key is not None else await env("GOOGLE_CLOUD_API_KEY")
+    if key:
+        return AuthResult(ModelAuth(api_key=key), source="stored credential" if stored_key else "GOOGLE_CLOUD_API_KEY")
+
+    credential_env = (credential.get("env") if credential else None) or {}
+    adc_path = credential_env.get("GOOGLE_APPLICATION_CREDENTIALS")
+    if adc_path is None:
+        adc_path = await env("GOOGLE_APPLICATION_CREDENTIALS")
+    signal.throw_if_aborted()
+    has_credentials = await ctx.file_exists(adc_path if adc_path is not None else VERTEX_ADC_PATH)
+    signal.throw_if_aborted()
+    project = credential_env.get("GOOGLE_CLOUD_PROJECT")
+    if project is None:
+        project = await env("GOOGLE_CLOUD_PROJECT")
+    if project is None:
+        project = await env("GCLOUD_PROJECT")
+    location = credential_env.get("GOOGLE_CLOUD_LOCATION")
+    if location is None:
+        location = await env("GOOGLE_CLOUD_LOCATION")
+    if has_credentials and project and location:
+        return AuthResult(
+            ModelAuth(),
+            env=credential.get("env") if credential else None,
+            source="stored credential" if credential else "gcloud application default credentials",
+        )
+    return None
+
+
+def vertex_auth() -> ApiKeyAuth:
+    """Vertex accepts an explicit API key or Application Default Credentials.
+
+    ADC (``gcloud auth application-default login``) additionally requires project
+    and location env vars, which the API implementation reads itself.
+    """
+    return ApiKeyAuth("Google Cloud credentials", _resolve, login=_login)
+
+
+def google_vertex_provider() -> Provider:
+    """Google Vertex AI with ``GOOGLE_CLOUD_API_KEY`` or Application Default Credentials."""
+    return create_provider(
+        id="google-vertex",
+        name="Google Vertex AI",
+        auth=ProviderAuth(api_key=vertex_auth()),
+        models=lambda: catalog_models("google-vertex"),
+        api=google_vertex_api(),
+    )

pi_ai/providers/groq.py

@@ -0,0 +1,23 @@
+"""Groq provider."""
+
+from __future__ import annotations
+
+from ..api.registry import openai_completions_api
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["groq_provider"]
+
+
+def groq_provider() -> Provider:
+    """Groq (OpenAI-compatible Chat Completions), authenticated with ``GROQ_API_KEY``."""
+    return create_provider(
+        id="groq",
+        name="Groq",
+        base_url="https://api.groq.com/openai/v1",
+        auth=ProviderAuth(api_key=env_api_key_auth("Groq API key", ["GROQ_API_KEY"])),
+        models=lambda: catalog_models("groq"),
+        api=openai_completions_api(),
+    )

pi_ai/providers/huggingface.py

@@ -0,0 +1,23 @@
+"""Hugging Face provider."""
+
+from __future__ import annotations
+
+from ..api.registry import openai_completions_api
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["huggingface_provider"]
+
+
+def huggingface_provider() -> Provider:
+    """Hugging Face (OpenAI-compatible Chat Completions), authenticated with ``HF_TOKEN``."""
+    return create_provider(
+        id="huggingface",
+        name="Hugging Face",
+        base_url="https://router.huggingface.co/v1",
+        auth=ProviderAuth(api_key=env_api_key_auth("Hugging Face token", ["HF_TOKEN"])),
+        models=lambda: catalog_models("huggingface"),
+        api=openai_completions_api(),
+    )

pi_ai/providers/kimi_coding.py

@@ -0,0 +1,32 @@
+"""Kimi For Coding provider."""
+
+from __future__ import annotations
+
+from ..api.registry import openai_completions_api
+from ..auth.helpers import env_api_key_auth, lazy_oauth
+from ..auth.oauth.load import load_kimi_coding_oauth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["kimi_coding_provider"]
+
+
+def kimi_coding_provider() -> Provider:
+    """Kimi For Coding: ``KIMI_API_KEY`` or a Kimi Code subscription login."""
+    return create_provider(
+        id="kimi-coding",
+        name="Kimi For Coding",
+        base_url="https://api.kimi.com/coding/v1",
+        auth=ProviderAuth(
+            api_key=env_api_key_auth("Kimi API key", ["KIMI_API_KEY"]),
+            oauth=lazy_oauth(
+                "Kimi Code (subscription)",
+                load_kimi_coding_oauth,
+                is_subscription=True,
+                login_label="Sign in with Kimi Code",
+            ),
+        ),
+        models=lambda: catalog_models("kimi-coding"),
+        api=openai_completions_api(),
+    )

pi_ai/providers/meta.py

@@ -0,0 +1,32 @@
+"""Meta provider."""
+
+from __future__ import annotations
+
+from ..api.registry import openai_responses_api
+from ..auth.helpers import env_api_key_auth, lazy_oauth
+from ..auth.oauth.load import load_meta_oauth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["meta_provider"]
+
+
+def meta_provider() -> Provider:
+    """Meta (OpenAI Responses API): ``META_API_KEY`` or a Muse subscription login."""
+    return create_provider(
+        id="meta",
+        name="Meta",
+        base_url="https://api.meta.ai/v1",
+        auth=ProviderAuth(
+            api_key=env_api_key_auth("Meta Model API key", ["META_API_KEY"]),
+            oauth=lazy_oauth(
+                "Meta (Muse subscription)",
+                load_meta_oauth,
+                is_subscription=True,
+                login_label="Sign in with Meta",
+            ),
+        ),
+        models=lambda: catalog_models("meta"),
+        api=openai_responses_api(),
+    )

pi_ai/providers/minimax.py

@@ -0,0 +1,23 @@
+"""MiniMax provider."""
+
+from __future__ import annotations
+
+from ..api.registry import anthropic_messages_api
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["minimax_provider"]
+
+
+def minimax_provider() -> Provider:
+    """MiniMax (Anthropic Messages API), authenticated with ``MINIMAX_API_KEY``."""
+    return create_provider(
+        id="minimax",
+        name="MiniMax",
+        base_url="https://api.minimax.io/anthropic",
+        auth=ProviderAuth(api_key=env_api_key_auth("MiniMax API key", ["MINIMAX_API_KEY"])),
+        models=lambda: catalog_models("minimax"),
+        api=anthropic_messages_api(),
+    )

pi_ai/providers/minimax_cn.py

@@ -0,0 +1,23 @@
+"""MiniMax CN provider."""
+
+from __future__ import annotations
+
+from ..api.registry import anthropic_messages_api
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["minimax_cn_provider"]
+
+
+def minimax_cn_provider() -> Provider:
+    """MiniMax CN (Anthropic Messages API), authenticated with ``MINIMAX_CN_API_KEY``."""
+    return create_provider(
+        id="minimax-cn",
+        name="MiniMax CN",
+        base_url="https://api.minimaxi.com/anthropic",
+        auth=ProviderAuth(api_key=env_api_key_auth("MiniMax CN API key", ["MINIMAX_CN_API_KEY"])),
+        models=lambda: catalog_models("minimax-cn"),
+        api=anthropic_messages_api(),
+    )

pi_ai/providers/mistral.py

@@ -0,0 +1,23 @@
+"""Mistral provider."""
+
+from __future__ import annotations
+
+from ..api.registry import mistral_conversations_api
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["mistral_provider"]
+
+
+def mistral_provider() -> Provider:
+    """Mistral (Mistral Conversations API), authenticated with ``MISTRAL_API_KEY``."""
+    return create_provider(
+        id="mistral",
+        name="Mistral",
+        base_url="https://api.mistral.ai",
+        auth=ProviderAuth(api_key=env_api_key_auth("Mistral API key", ["MISTRAL_API_KEY"])),
+        models=lambda: catalog_models("mistral"),
+        api=mistral_conversations_api(),
+    )

pi_ai/providers/moonshotai.py

@@ -0,0 +1,23 @@
+"""Moonshot AI provider."""
+
+from __future__ import annotations
+
+from ..api.registry import openai_completions_api
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["moonshotai_provider"]
+
+
+def moonshotai_provider() -> Provider:
+    """Moonshot AI (OpenAI-compatible Chat Completions), authenticated with ``MOONSHOT_API_KEY``."""
+    return create_provider(
+        id="moonshotai",
+        name="Moonshot AI",
+        base_url="https://api.moonshot.ai/v1",
+        auth=ProviderAuth(api_key=env_api_key_auth("Moonshot AI API key", ["MOONSHOT_API_KEY"])),
+        models=lambda: catalog_models("moonshotai"),
+        api=openai_completions_api(),
+    )

pi_ai/providers/moonshotai_cn.py

@@ -0,0 +1,23 @@
+"""Moonshot AI CN provider."""
+
+from __future__ import annotations
+
+from ..api.registry import openai_completions_api
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["moonshotai_cn_provider"]
+
+
+def moonshotai_cn_provider() -> Provider:
+    """Moonshot AI CN (OpenAI-compatible Chat Completions), authenticated with ``MOONSHOT_API_KEY``."""
+    return create_provider(
+        id="moonshotai-cn",
+        name="Moonshot AI CN",
+        base_url="https://api.moonshot.cn/v1",
+        auth=ProviderAuth(api_key=env_api_key_auth("Moonshot AI API key", ["MOONSHOT_API_KEY"])),
+        models=lambda: catalog_models("moonshotai-cn"),
+        api=openai_completions_api(),
+    )

pi_ai/providers/nvidia.py

@@ -0,0 +1,23 @@
+"""NVIDIA provider."""
+
+from __future__ import annotations
+
+from ..api.registry import openai_completions_api
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["nvidia_provider"]
+
+
+def nvidia_provider() -> Provider:
+    """NVIDIA (OpenAI-compatible Chat Completions), authenticated with ``NVIDIA_API_KEY``."""
+    return create_provider(
+        id="nvidia",
+        name="NVIDIA",
+        base_url="https://integrate.api.nvidia.com/v1",
+        auth=ProviderAuth(api_key=env_api_key_auth("NVIDIA API key", ["NVIDIA_API_KEY"])),
+        models=lambda: catalog_models("nvidia"),
+        api=openai_completions_api(),
+    )

pi_ai/providers/openai.py

@@ -0,0 +1,44 @@
+"""OpenAI provider."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ..api.registry import openai_decisions_api, openai_responses_api
+from ..auth.helpers import env_api_key_auth, lazy_oauth
+from ..auth.oauth.load import load_openai_chatgpt_oauth
+from ..auth.types import Credential, ProviderAuth
+from ..models import Provider, create_provider, is_model_type
+from ..types import AnyModel
+from .catalog import catalog_models
+
+__all__ = ["openai_provider"]
+
+
+def _filter_all_models(models: Sequence[AnyModel], credential: Credential | None) -> Sequence[AnyModel]:
+    # Sign in with ChatGPT tokens only reach the Responses API; the Decisions API rejects them.
+    if credential is not None and credential.get("type") == "oauth":
+        return [model for model in models if not is_model_type(model, "classifier")]
+    return models
+
+
+def openai_provider() -> Provider:
+    """OpenAI (Responses API plus Decisions classifiers): ``OPENAI_API_KEY`` or Sign in with ChatGPT."""
+    return create_provider(
+        id="openai",
+        name="OpenAI",
+        base_url="https://api.openai.com/v1",
+        auth=ProviderAuth(
+            api_key=env_api_key_auth("OpenAI API key", ["OPENAI_API_KEY"]),
+            oauth=lazy_oauth(
+                "OpenAI (ChatGPT subscription)",
+                load_openai_chatgpt_oauth,
+                is_subscription=True,
+                login_label="Sign in with ChatGPT",
+            ),
+        ),
+        models=lambda: catalog_models("openai"),
+        filter_all_models=_filter_all_models,
+        api=openai_responses_api(),
+        classifiers={"openai-decisions": openai_decisions_api()},
+    )

pi_ai/providers/openai_codex.py

@@ -0,0 +1,26 @@
+"""OpenAI Codex (legacy ChatGPT backend) provider."""
+
+from __future__ import annotations
+
+from ..api.registry import openai_codex_responses_api
+from ..auth.helpers import lazy_oauth
+from ..auth.oauth.load import load_openai_codex_oauth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+
+__all__ = ["openai_codex_provider"]
+
+
+def openai_codex_provider() -> Provider:
+    """OpenAI Codex through the ChatGPT backend; OAuth (ChatGPT Plus/Pro) only."""
+    return create_provider(
+        id="openai-codex",
+        name="OpenAI Codex (legacy)",
+        base_url="https://chatgpt.com/backend-api",
+        auth=ProviderAuth(
+            oauth=lazy_oauth("OpenAI (ChatGPT Plus/Pro)", load_openai_codex_oauth, is_subscription=True),
+        ),
+        models=lambda: catalog_models("openai-codex"),
+        api=openai_codex_responses_api(),
+    )

pi_ai/providers/opencode.py

@@ -0,0 +1,36 @@
+"""OpenCode Zen provider."""
+
+from __future__ import annotations
+
+from ..api.registry import (
+    anthropic_messages_api,
+    google_generative_ai_api,
+    openai_completions_api,
+    openai_responses_api,
+    typesafe_system_one_api,
+)
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+from .opencode_headers import with_opencode_session_header
+
+__all__ = ["opencode_provider"]
+
+
+def opencode_provider() -> Provider:
+    """OpenCode Zen (mixed APIs), authenticated with ``OPENCODE_API_KEY``."""
+    return create_provider(
+        id="opencode",
+        name="OpenCode Zen",
+        auth=ProviderAuth(api_key=env_api_key_auth("OpenCode API key", ["OPENCODE_API_KEY"])),
+        models=lambda: catalog_models("opencode"),
+        api={
+            "anthropic-messages": with_opencode_session_header(anthropic_messages_api()),
+            "google-generative-ai": with_opencode_session_header(google_generative_ai_api()),
+            "openai-completions": with_opencode_session_header(openai_completions_api()),
+            "openai-responses": with_opencode_session_header(openai_responses_api()),
+        },
+        # OpenCode Zen serves TypeSafe's System One protocol at /zen/v1/systemone.
+        classifiers={"typesafe-system-one": typesafe_system_one_api()},
+    )

pi_ai/providers/opencode_go.py

@@ -0,0 +1,33 @@
+"""OpenCode Go provider."""
+
+from __future__ import annotations
+
+from ..api.registry import (
+    anthropic_messages_api,
+    google_generative_ai_api,
+    openai_completions_api,
+    openai_responses_api,
+)
+from ..auth.helpers import env_api_key_auth
+from ..auth.types import ProviderAuth
+from ..models import Provider, create_provider
+from .catalog import catalog_models
+from .opencode_headers import with_opencode_session_header
+
+__all__ = ["opencode_go_provider"]
+
+
+def opencode_go_provider() -> Provider:
+    """OpenCode Go (mixed APIs), authenticated with ``OPENCODE_API_KEY``."""
+    return create_provider(
+        id="opencode-go",
+        name="OpenCode Go",
+        auth=ProviderAuth(api_key=env_api_key_auth("OpenCode API key", ["OPENCODE_API_KEY"])),
+        models=lambda: catalog_models("opencode-go"),
+        api={
+            "anthropic-messages": with_opencode_session_header(anthropic_messages_api()),
+            "google-generative-ai": with_opencode_session_header(google_generative_ai_api()),
+            "openai-completions": with_opencode_session_header(openai_completions_api()),
+            "openai-responses": with_opencode_session_header(openai_responses_api()),
+        },
+    )

pi_ai/providers/opencode_headers.py

@@ -0,0 +1,60 @@
+"""OpenCode's per-conversation routing header."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ..event_stream import AssistantMessageEventStream
+from ..types import Model, TranscriptContext
+
+__all__ = ["OPENCODE_SESSION_HEADER", "with_opencode_session_header"]
+
+OPENCODE_SESSION_HEADER = "x-opencode-session"
+
+
+def _has_header(headers: Mapping[str, Any] | None, name: str) -> bool:
+    # Any caller entry counts, including a ``None`` suppression marker.
+    expected = name.lower()
+    return any(key.lower() == expected for key in headers or {})
+
+
+def _with_session_header(options: Mapping[str, Any] | None) -> Mapping[str, Any] | None:
+    if not options or not options.get("session_id") or _has_header(options.get("headers"), OPENCODE_SESSION_HEADER):
+        return options
+    return {
+        **options,
+        "headers": {**(options.get("headers") or {}), OPENCODE_SESSION_HEADER: options["session_id"]},
+    }
+
+
+class _OpenCodeStreams:
+    """Delegating ``ProviderStreams`` that keeps the wrapped deferred capabilities."""
+
+    __slots__ = ("_streams", "cancel_deferred", "fetch_deferred")
+
+    def __init__(self, streams: Any) -> None:
+        self._streams = streams
+        self.fetch_deferred = getattr(streams, "fetch_deferred", None)
+        self.cancel_deferred = getattr(streams, "cancel_deferred", None)
+
+    def stream(
+        self, model: Model, context: TranscriptContext, options: Mapping[str, Any] | None = None
+    ) -> AssistantMessageEventStream:
+        return self._streams.stream(model, context, _with_session_header(options))
+
+    def stream_simple(
+        self, model: Model, context: TranscriptContext, options: Mapping[str, Any] | None = None
+    ) -> AssistantMessageEventStream:
+        return self._streams.stream_simple(model, context, _with_session_header(options))
+
+    def __repr__(self) -> str:
+        return f"with_opencode_session_header({self._streams!r})"
+
+
+def with_opencode_session_header(streams: Any) -> Any:
+    """Add OpenCode's required ``x-opencode-session`` header from ``session_id`` before API dispatch.
+
+    A caller-supplied header with the same name (any case, including ``None``) wins.
+    """
+    return _OpenCodeStreams(streams)