copilotkit 0.1.90__tar.gz → 0.1.92__tar.gz

{copilotkit-0.1.90 → copilotkit-0.1.92}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: copilotkit
-Version: 0.1.90
+Version: 0.1.92
 Summary: CopilotKit python SDK
 License: MIT
 Keywords: copilot,copilotkit,langgraph,langchain,ai,langsmith,langserve

{copilotkit-0.1.90 → copilotkit-0.1.92}/copilotkit/__init__.py

@@ -7,6 +7,14 @@ from .sdk import (
     CopilotKitSDKContext,
 )
 from .action import Action
+from .exc import (
+    CopilotKitError,
+    CopilotKitMisuseError,
+    ActionNotFoundException,
+    AgentNotFoundException,
+    ActionExecutionException,
+    AgentExecutionException,
+)
 from .langgraph import CopilotKitState
 from .parameter import Parameter
 from .agent import Agent
@@ -32,6 +40,12 @@ __all__ = [
     "Agent",
     "CopilotKitContext",
     "CopilotKitSDKContext",
+    "CopilotKitError",
+    "CopilotKitMisuseError",
+    "ActionNotFoundException",
+    "AgentNotFoundException",
+    "ActionExecutionException",
+    "AgentExecutionException",
     "CrewAIAgent",  # pyright: ignore[reportUnsupportedDunderAll] pylint: disable=undefined-all-variable
     "LangGraphAGUIAgent",
     "CopilotKitMiddleware",

{copilotkit-0.1.90 → copilotkit-0.1.92}/copilotkit/copilotkit_lg_middleware.py

@@ -16,7 +16,7 @@ Example:
 
 import json
 import re
-from typing import Any, Callable, Awaitable, ClassVar, Iterable, List, Union
+from typing import Any, Callable, Awaitable, ClassVar, Iterable, Union
 
 from langchain_core.messages import AIMessage, SystemMessage, ToolMessage
 from langchain.agents.middleware import (
@@ -27,7 +27,7 @@ from langchain.agents.middleware import (
 )
 from langgraph.runtime import Runtime
 
-from .header_propagation import install_httpx_hook
+from .header_propagation import install_httpx_hook, set_forwarded_headers
 from .langgraph import CopilotKitProperties
 
 # Track which httpx clients already have the header-propagation hook installed
@@ -35,6 +35,99 @@ from .langgraph import CopilotKitProperties
 _hooked_clients: set[int] = set()
 
 
+def _extract_forwarded_headers_from_config() -> None:
+    """Extract raw ``x-*`` headers from the current LangGraph RunnableConfig and
+    push them into the header-propagation ContextVar so the httpx hook can
+    forward them on outgoing LLM requests.
+
+    When an agent runs inside **langgraph-api** with
+    ``LANGGRAPH_HTTP={"configurable_headers":{"include":["x-*"]}}``,
+    the server copies inbound HTTP ``x-*`` headers into
+    ``config["configurable"]`` as individual keys (e.g.
+    ``configurable["x-aimock-context"] = "value"``).  This function reads those
+    keys and calls :func:`set_forwarded_headers` so they propagate to the
+    underlying LLM provider SDK via the httpx event hook.
+
+    Precedence: the wrapper dict ``copilotkit_forwarded_headers`` (if present)
+    takes priority over raw ``x-*`` keys.  Raw keys are only used when the
+    wrapper dict is absent or does not contain a given header.
+
+    Safe to call outside a runnable context (e.g. in unit tests) — silently
+    returns without doing anything if ``get_config()`` raises.
+    """
+    try:
+        from langgraph.config import (
+            get_config,
+        )  # local import to avoid hard dep at module level
+
+        config = get_config()
+    except ImportError:
+        return
+    except RuntimeError:
+        # No active runnable context — clear the ContextVar so stale headers
+        # from a prior request in the same async context do not leak through.
+        set_forwarded_headers({})
+        return
+
+    try:
+        headers: dict[str, str] = {}
+
+        # Sources to scan: config["context"] (LangGraph >=0.6.0) and
+        # config["configurable"] (all versions).
+        context = config.get("context") or {}
+        configurable = config.get("configurable") or {}
+
+        # 1) Wrapper-dict path (highest priority): these are headers that
+        #    CopilotKit explicitly bundled under a known key.  Process context
+        #    first with first-write-wins so context takes precedence over
+        #    configurable (LangGraph >=0.6.0 introduced context as the newer
+        #    preferred mechanism).
+        for src in (context, configurable):
+            if not isinstance(src, dict):
+                continue
+            wrapper = src.get("copilotkit_forwarded_headers")
+            if isinstance(wrapper, dict):
+                for k, v in wrapper.items():
+                    lk = k.lower() if isinstance(k, str) else k
+                    if isinstance(k, str) and isinstance(v, str) and lk not in headers:
+                        headers[lk] = v
+
+        # 2) Raw x-* keys directly on context and configurable.  These appear
+        #    when langgraph-api's configurable_headers mechanism forwards inbound
+        #    HTTP headers as individual configurable entries.
+        for src in (context, configurable):
+            if not isinstance(src, dict):
+                continue
+            for k, v in src.items():
+                if (
+                    isinstance(k, str)
+                    and k.lower().startswith("x-")
+                    and isinstance(v, str)
+                ):
+                    # Don't overwrite wrapper-dict values (wrapper > raw).
+                    # Lowercase at insertion so precedence checks are
+                    # deterministic regardless of source casing.
+                    lk = k.lower()
+                    if lk not in headers:
+                        headers[lk] = v
+
+        # Always set the ContextVar — even with an empty dict — so stale
+        # headers from previous calls in the same async context do not leak
+        # into this one.
+        set_forwarded_headers(headers)
+    except Exception as e:
+        # Header forwarding is best-effort.  Never block the LLM call.
+        # Clear the ContextVar so stale headers from a prior request do not
+        # leak through on failure.
+        set_forwarded_headers({})
+        import logging
+
+        logging.getLogger(__name__).debug(
+            "Header forwarding extraction failed; continuing without forwarded headers: %s",
+            e,
+        )
+
+
 def _ensure_httpx_hook(model: Any) -> None:
     """Install the header-propagation httpx hook on a LangChain chat model's
     underlying HTTP client(s), if present.  No-op for models that don't expose
@@ -172,6 +265,7 @@ class CopilotKitMiddleware(AgentMiddleware[StateSchema, Any]):
         request: ModelRequest,
         handler: Callable[[ModelRequest], ModelResponse],
     ) -> ModelResponse:
+        _extract_forwarded_headers_from_config()
         _ensure_httpx_hook(request.model)
         request = self._apply_state_note(request)
         frontend_tools = request.state.get("copilotkit", {}).get("actions", [])
@@ -361,6 +455,7 @@ class CopilotKitMiddleware(AgentMiddleware[StateSchema, Any]):
         request: ModelRequest,
         handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
     ) -> ModelResponse:
+        _extract_forwarded_headers_from_config()
         _ensure_httpx_hook(request.model)
         self._fix_messages_for_bedrock(request.messages)
         request = self._apply_state_note(request)

{copilotkit-0.1.90 → copilotkit-0.1.92}/copilotkit/crewai/crewai_sdk.py

@@ -5,7 +5,8 @@ CrewAI integration for CopilotKit
 import uuid
 import json
 import asyncio
-from typing_extensions import Any, Dict, List, Literal
+from typing_extensions import Any, Dict, List, Literal, Optional
+from copilotkit.exc import CopilotKitMisuseError
 from pydantic import BaseModel, Field
 from litellm.types.utils import (
     ModelResponse,
@@ -226,14 +227,19 @@ async def copilotkit_emit_message(message: str) -> str:
     return message_id
 
 
-async def copilotkit_emit_tool_call(*, name: str, args: Dict[str, Any]) -> str:
+async def copilotkit_emit_tool_call(
+    *, name: str, args: Dict[str, Any], tool_call_id: Optional[str] = None
+) -> str:
     """
     Manually emits a tool call to CopilotKit.
 
     ```python
     from copilotkit.crewai import copilotkit_emit_tool_call
 
-    await copilotkit_emit_tool_call(name="SearchTool", args={"steps": 10})
+    auto_id = await copilotkit_emit_tool_call(name="SearchTool", args={"steps": 10})
+
+    # With a custom ID for correlation/idempotency:
+    custom_id = await copilotkit_emit_tool_call(name="SearchTool", args={"steps": 10}, tool_call_id="my-custom-id")
     ```
 
     Parameters
@@ -242,22 +248,57 @@ async def copilotkit_emit_tool_call(*, name: str, args: Dict[str, Any]) -> str:
         The name of the tool to emit.
     args : Dict[str, Any]
         The arguments to emit.
+    tool_call_id : Optional[str]
+        Optional tool call ID. If not provided, a random UUID is generated.
+        When provided, this ID is used as both the toolCallId and
+        parentMessageId in AG-UI protocol events.
+        The caller is responsible for ensuring uniqueness.
 
     Returns
     -------
-    Awaitable[bool]
-        Always return True.
+    str
+        The tool call ID used for the emitted tool call.
     """
-    message_id = str(uuid.uuid4())
-    await queue_put(
-        action_execution_start(
-            action_execution_id=message_id,
-            action_name=name,
-            parent_message_id=message_id,
-        ),
-        action_execution_args(action_execution_id=message_id, args=json.dumps(args)),
-        action_execution_end(action_execution_id=message_id),
-    )
+    if not isinstance(name, str) or not name.strip():
+        raise CopilotKitMisuseError(
+            "Tool name must be a non-empty string for copilotkit_emit_tool_call"
+        )
+
+    if tool_call_id is not None:
+        if not isinstance(tool_call_id, str) or not tool_call_id.strip():
+            raise CopilotKitMisuseError(
+                "Tool call id must be a non-empty string when provided for copilotkit_emit_tool_call"
+            )
+    try:
+        args_json = json.dumps(args)
+    except (TypeError, ValueError) as e:
+        raise CopilotKitMisuseError(
+            f"Tool arguments for '{name}' are not JSON-serializable: {e}"
+        ) from e
+
+    message_id = tool_call_id if tool_call_id is not None else str(uuid.uuid4())
+    try:
+        await queue_put(
+            action_execution_start(
+                action_execution_id=message_id,
+                action_name=name,
+                parent_message_id=message_id,
+            ),
+            action_execution_args(action_execution_id=message_id, args=args_json),
+            action_execution_end(action_execution_id=message_id),
+        )
+    except Exception:
+        try:
+            await queue_put(
+                action_execution_end(action_execution_id=message_id),
+            )
+        except Exception:
+            logger.error(
+                "Failed to emit compensating action_execution_end for %s",
+                message_id,
+                exc_info=True,
+            )
+        raise
 
     return message_id
 

{copilotkit-0.1.90 → copilotkit-0.1.92}/copilotkit/exc.py

@@ -1,7 +1,16 @@
 """Exceptions for CopilotKit."""
 
 
-class ActionNotFoundException(Exception):
+class CopilotKitError(Exception):
+    """Base exception for all CopilotKit errors.
+
+    Catch this to handle any CopilotKit-specific exception.
+    """
+
+    pass
+
+
+class ActionNotFoundException(CopilotKitError):
     """Exception raised when an action or agent is not found."""
 
     def __init__(self, name: str):
@@ -9,7 +18,7 @@ class ActionNotFoundException(Exception):
         super().__init__(f"Action '{name}' not found.")
 
 
-class AgentNotFoundException(Exception):
+class AgentNotFoundException(CopilotKitError):
     """Exception raised when an agent is not found."""
 
     def __init__(self, name: str):
@@ -17,7 +26,7 @@ class AgentNotFoundException(Exception):
         super().__init__(f"Agent '{name}' not found.")
 
 
-class ActionExecutionException(Exception):
+class ActionExecutionException(CopilotKitError):
     """Exception raised when an action fails to execute."""
 
     def __init__(self, name: str, error: Exception):
@@ -26,10 +35,20 @@ class ActionExecutionException(Exception):
         super().__init__(f"Action '{name}' failed to execute: {error}")
 
 
-class AgentExecutionException(Exception):
+class AgentExecutionException(CopilotKitError):
     """Exception raised when an agent fails to execute."""
 
     def __init__(self, name: str, error: Exception):
         self.name = name
         self.error = error
         super().__init__(f"Agent '{name}' failed to execute: {error}")
+
+
+class CopilotKitMisuseError(CopilotKitError, ValueError):
+    """Exception raised when CopilotKit detects incorrect usage of its APIs.
+
+    Inherits from both CopilotKitError (for ``except CopilotKitError``) and
+    ValueError (for backward compatibility with ``except ValueError`` handlers).
+    """
+
+    pass

copilotkit-0.1.92/copilotkit/header_propagation.py

@@ -0,0 +1,201 @@
+"""Forward CopilotKit request-context headers onto outbound LLM/provider HTTP calls
+so downstream services (e.g. the aimock test server, proxies, request routing /
+fixture-matching infrastructure) can correlate the outbound provider call with the
+original inbound request.
+
+What this module does
+---------------------
+On each inbound request the application stores a small set of ``x-*`` prefixed
+headers (for example ``x-aimock-context``, ``x-aimock-session``, ``x-request-id``,
+``x-trace-id``) on a per-request ``contextvars.ContextVar``. When the application
+later makes an outbound HTTP call to an LLM provider (OpenAI, Anthropic, or any
+client that wraps ``httpx``), an httpx request event hook reads that ContextVar
+and copies those same headers onto the outbound request so downstream services
+can correlate the two.
+
+This is plain header propagation, not data collection. Scope and limits:
+
+* Only headers the application itself set on the request context via
+  ``set_forwarded_headers`` are forwarded. The module never reads request
+  bodies, cookies, user data, credentials, or anything off the inbound
+  request beyond the headers explicitly handed to it.
+* Only ``x-*`` prefixed headers pass the filter; ``authorization``,
+  ``content-type``, and any other non ``x-*`` headers are dropped.
+* Nothing is collected, persisted, logged, or sent anywhere by this module
+  itself — it only attaches headers to an HTTP request that the caller was
+  already going to make. There is no telemetry, no out-of-band channel, and
+  no end-user data flow.
+
+Mechanics
+---------
+``install_httpx_hook`` does two small things:
+
+1. It walks the ``._client`` chain on the given object (modern provider SDKs
+   wrap their httpx client behind several layers of ``._client``) to find the
+   first object that exposes an httpx-style ``event_hooks`` mapping.
+2. It attaches a request event hook to that mapping. The hook flavor matches
+   the client: an async coroutine hook for ``httpx.AsyncClient`` (httpx awaits
+   request hooks on async clients), and a plain sync hook for ``httpx.Client``.
+   Installation is idempotent via a marker attribute on the installed callable.
+
+This mirrors the CopilotKit runtime's ``extractForwardableHeaders()`` behavior
+on the Node side so the Python SDK forwards the same set of context headers.
+"""
+
+import contextvars
+import warnings
+from typing import Any, Dict, Optional
+
+# Per-request storage for the set of headers the application has asked to forward
+# onto outbound LLM/provider calls (populated by ``set_forwarded_headers``).
+_forwarded_headers: contextvars.ContextVar[Dict[str, str]] = contextvars.ContextVar(
+    "copilotkit_forwarded_headers"
+)
+
+# Marker used to identify hooks we have already installed, so install_httpx_hook
+# is idempotent across repeated calls on the same client.
+_HOOK_MARKER = "_copilotkit_forwarded_header_hook"
+
+# Bound on how deep we'll walk a ``._client`` chain looking for event_hooks.
+# The modern OpenAI SDK shape is:
+#   ChatOpenAI.client -> Completions/AsyncCompletions resource
+#     -> ._client = openai.OpenAI / AsyncOpenAI  (no event_hooks)
+#     -> ._client._client = httpx wrapper        (HAS event_hooks)
+# 5 hops is plenty of headroom for similar SDKs without risking pathological loops.
+_MAX_CHAIN_DEPTH = 5
+
+
+def set_forwarded_headers(headers: Dict[str, str]) -> None:
+    """Record the set of headers to forward onto outbound LLM/provider calls
+    made later in this request context.
+
+    Only ``x-*`` prefixed headers are kept; everything else is dropped.
+    """
+    filtered = {k.lower(): v for k, v in headers.items() if k.lower().startswith("x-")}
+    _forwarded_headers.set(filtered)
+
+
+def get_forwarded_headers() -> Dict[str, str]:
+    """Return the headers the application has asked to forward onto outbound
+    LLM/provider calls in the current request context."""
+    return _forwarded_headers.get({})
+
+
+def _find_event_hooks_target(client: Any) -> Optional[Any]:
+    """Walk the ``._client`` chain looking for the first object that exposes
+    an httpx-style ``event_hooks`` mapping.
+
+    Returns the target object, or ``None`` if no such object is found within
+    ``_MAX_CHAIN_DEPTH`` hops.
+    """
+    current = client
+    for _ in range(_MAX_CHAIN_DEPTH + 1):
+        if current is None:
+            return None
+        if hasattr(current, "event_hooks"):
+            return current
+        nxt = getattr(current, "_client", None)
+        if nxt is current or nxt is None:
+            return None
+        current = nxt
+    return None
+
+
+def install_httpx_hook(client: Any) -> None:
+    """Attach a request event hook to ``client``'s underlying httpx client so
+    that headers recorded via ``set_forwarded_headers`` are copied onto
+    outbound requests.
+
+    Works with OpenAI and Anthropic Python SDKs (both wrap httpx internally,
+    sometimes via several layers of ``._client`` indirection), as well as raw
+    ``httpx.Client`` / ``httpx.AsyncClient`` instances.
+
+    For ``httpx.AsyncClient`` an async hook is attached (httpx awaits request
+    hooks on async clients); for sync clients a sync hook is attached.
+
+    Idempotent: a marker attribute on the installed callable prevents double
+    installation on the same target.
+
+    Parameters
+    ----------
+    client : object
+        An OpenAI/Anthropic client instance, or a raw httpx.Client/AsyncClient.
+    """
+    target = _find_event_hooks_target(client)
+
+    if target is None:
+        warnings.warn(
+            f"install_httpx_hook: client of type {type(client).__name__} has no "
+            "recognized event_hooks attribute; x-* headers will not be forwarded",
+            stacklevel=2,
+        )
+        return
+
+    request_hooks = target.event_hooks.get("request", [])
+
+    # Idempotency: don't double-install on the same target.
+    for existing in request_hooks:
+        if getattr(existing, _HOOK_MARKER, False):
+            return
+
+    # Choose sync vs async hook flavor based on the target class.
+    # httpx.AsyncClient awaits request hooks; a sync hook returning None would
+    # raise "TypeError: object NoneType can't be used in 'await' expression",
+    # which surfaces as APIConnectionError to the caller.
+    is_async = _is_async_httpx_target(target)
+
+    if is_async:
+
+        async def _inject_headers_async(request):
+            headers = get_forwarded_headers()
+            for key, value in headers.items():
+                request.headers[key] = value
+
+        setattr(_inject_headers_async, _HOOK_MARKER, True)
+        request_hooks.append(_inject_headers_async)
+    else:
+
+        def _inject_headers(request):
+            headers = get_forwarded_headers()
+            for key, value in headers.items():
+                request.headers[key] = value
+
+        setattr(_inject_headers, _HOOK_MARKER, True)
+        request_hooks.append(_inject_headers)
+
+    # In case ``event_hooks`` returned a fresh list (defensive), make sure the
+    # mutation is reflected on the target.
+    target.event_hooks["request"] = request_hooks
+
+
+def _is_async_httpx_target(target: Any) -> bool:
+    """Best-effort detection: is this object an httpx async client?
+
+    Tries ``isinstance`` against the real ``httpx.AsyncClient`` / ``httpx.Client``
+    first (the authoritative answer for real clients). If httpx is not
+    importable, or the target is neither of those (e.g. a wrapped or
+    duck-typed client used in tests), falls back to an EXACT MRO class-name
+    match against ``"AsyncClient"``. Avoids a broad ``startswith("Async")``
+    check, which would misclassify a sync client whose MRO happens to
+    include an ``Async*``-named base (e.g. ``AsyncContextManager``) as
+    async — attaching an async hook that httpx calls synchronously would
+    leave the coroutine unawaited and the forwarded headers would not be
+    attached to the outbound request.
+    """
+    try:
+        import httpx  # local import keeps httpx an optional concern at import time
+
+        if isinstance(target, httpx.AsyncClient):
+            return True
+        if isinstance(target, httpx.Client):
+            return False
+    except (
+        ImportError
+    ):  # pragma: no cover - httpx should always be importable in practice
+        pass
+
+    # Fall back to exact class-name match for wrapped/duck-typed clients.
+    for cls in type(target).__mro__:
+        if cls.__name__ == "AsyncClient":
+            return True
+    return False

{copilotkit-0.1.90 → copilotkit-0.1.92}/copilotkit/langgraph.py

@@ -23,6 +23,7 @@ from langchain_core.callbacks.manager import adispatch_custom_event
 from langgraph.types import interrupt
 
 from .types import Message, IntermediateStateConfig
+from .exc import CopilotKitMisuseError
 from .logging import get_logger
 
 logger = get_logger(__name__)
@@ -368,21 +369,28 @@ async def copilotkit_emit_message(config: RunnableConfig, message: str):
         {"message": message, "message_id": str(uuid.uuid4()), "role": "assistant"},
         config=config,
     )
-    await asyncio.sleep(0.02)
+    await asyncio.shield(asyncio.sleep(0.02))
 
     return True
 
 
 async def copilotkit_emit_tool_call(
-    config: RunnableConfig, *, name: str, args: Dict[str, Any]
-):
+    config: RunnableConfig,
+    *,
+    name: str,
+    args: Dict[str, Any],
+    tool_call_id: Optional[str] = None,
+) -> str:
     """
     Manually emits a tool call to CopilotKit.
 
     ```python
     from copilotkit.langgraph import copilotkit_emit_tool_call
 
-    await copilotkit_emit_tool_call(config, name="SearchTool", args={"steps": 10})
+    auto_id = await copilotkit_emit_tool_call(config, name="SearchTool", args={"steps": 10})
+
+    # With a custom ID for correlation/idempotency:
+    custom_id = await copilotkit_emit_tool_call(config, name="SearchTool", args={"steps": 10}, tool_call_id="my-custom-id")
     ```
 
     Parameters
@@ -393,21 +401,56 @@ async def copilotkit_emit_tool_call(
         The name of the tool to emit.
     args : Dict[str, Any]
         The arguments to emit.
+    tool_call_id : Optional[str]
+        Optional tool call ID. If not provided, a random UUID is generated.
+        When provided, this ID is used as the toolCallId and parentMessageId
+        in AG-UI protocol events. The caller is responsible for ensuring uniqueness.
 
     Returns
     -------
-    Awaitable[bool]
-        Always return True.
+    str
+        The tool call ID used for the emitted tool call.
     """
+    if not isinstance(name, str) or not name.strip():
+        raise CopilotKitMisuseError(
+            "Tool name must be a non-empty string for copilotkit_emit_tool_call"
+        )
+
+    if tool_call_id is not None:
+        if not isinstance(tool_call_id, str) or not tool_call_id.strip():
+            raise CopilotKitMisuseError(
+                "Tool call id must be a non-empty string when provided for copilotkit_emit_tool_call"
+            )
+    else:
+        tool_call_id = str(uuid.uuid4())
+
+    try:
+        json.dumps(args)
+    except (TypeError, ValueError) as e:
+        raise CopilotKitMisuseError(
+            f"Tool arguments for '{name}' are not JSON-serializable: {e}"
+        ) from e
 
     await adispatch_custom_event(
         "copilotkit_manually_emit_tool_call",
-        {"name": name, "args": args, "id": str(uuid.uuid4())},
+        {"name": name, "args": args, "id": tool_call_id},
         config=config,
     )
-    await asyncio.sleep(0.02)
+    # LangGraph's adispatch_custom_event is async but does not guarantee the event
+    # has been flushed to the SSE stream before it returns. Without this sleep,
+    # a subsequent emit can interleave and corrupt event ordering on the client.
+    # Shielded so that task cancellation doesn't prevent us from returning the ID.
+    try:
+        await asyncio.shield(asyncio.sleep(0.02))
+    except asyncio.CancelledError:
+        logger.warning(
+            "copilotkit_emit_tool_call cancelled during post-dispatch flush for "
+            "tool_call_id=%s; event was already dispatched",
+            tool_call_id,
+        )
+        raise
 
-    return True
+    return tool_call_id
 
 
 def copilotkit_interrupt(

{copilotkit-0.1.90 → copilotkit-0.1.92}/copilotkit/langgraph_agui_agent.py

@@ -1,6 +1,10 @@
 import json
+import logging
 from typing import Dict, Any, List, Optional, Union, AsyncGenerator
 from enum import Enum
+from .exc import CopilotKitMisuseError
+
+logger = logging.getLogger(__name__)
 from ag_ui_langgraph import LangGraphAgent
 from ag_ui.core import (
     EventType,
@@ -104,33 +108,86 @@ class LangGraphAGUIAgent(LangGraphAgent):
                 return super()._dispatch_event(event)
 
             if custom_event.name == CustomEventNames.ManuallyEmitToolCall.value:
-                # Emit the tool call events
-                super()._dispatch_event(
-                    ToolCallStartEvent(
-                        type=EventType.TOOL_CALL_START,
-                        tool_call_id=custom_event.value["id"],
-                        tool_call_name=custom_event.value["name"],
-                        parent_message_id=custom_event.value["id"],
-                        raw_event=event,
+                value = custom_event.value
+                if not isinstance(value, dict):
+                    raise CopilotKitMisuseError(
+                        f"ManuallyEmitToolCall event 'value' must be a dict, got {type(value).__name__}"
                     )
-                )
-                super()._dispatch_event(
-                    ToolCallArgsEvent(
-                        type=EventType.TOOL_CALL_ARGS,
-                        tool_call_id=custom_event.value["id"],
-                        delta=custom_event.value["args"]
-                        if isinstance(custom_event.value["args"], str)
-                        else json.dumps(custom_event.value["args"]),
-                        raw_event=event,
+
+                tool_call_id = value.get("id")
+                tool_call_name = value.get("name")
+                tool_call_args = value.get("args")
+
+                if not isinstance(tool_call_id, str) or not tool_call_id.strip():
+                    raise CopilotKitMisuseError(
+                        f"ManuallyEmitToolCall event missing valid 'id': got {type(tool_call_id).__name__}"
                     )
-                )
-                super()._dispatch_event(
-                    ToolCallEndEvent(
-                        type=EventType.TOOL_CALL_END,
-                        tool_call_id=custom_event.value["id"],
-                        raw_event=event,
+                if not isinstance(tool_call_name, str) or not tool_call_name.strip():
+                    raise CopilotKitMisuseError(
+                        f"ManuallyEmitToolCall event missing valid 'name': got {type(tool_call_name).__name__}"
                     )
-                )
+                if tool_call_args is None:
+                    raise CopilotKitMisuseError(
+                        f"ManuallyEmitToolCall event missing 'args' for tool_call_id={tool_call_id}"
+                    )
+
+                try:
+                    delta = (
+                        tool_call_args
+                        if isinstance(tool_call_args, str)
+                        else json.dumps(tool_call_args)
+                    )
+                except (TypeError, ValueError) as e:
+                    raise CopilotKitMisuseError(
+                        f"ManuallyEmitToolCall 'args' is not JSON-serializable for tool_call_id={tool_call_id}: {e}"
+                    ) from e
+
+                dispatched_start = False
+                end_dispatched = False
+                try:
+                    super()._dispatch_event(
+                        ToolCallStartEvent(
+                            type=EventType.TOOL_CALL_START,
+                            tool_call_id=tool_call_id,
+                            tool_call_name=tool_call_name,
+                            parent_message_id=tool_call_id,
+                            raw_event=event,
+                        )
+                    )
+                    dispatched_start = True
+                    super()._dispatch_event(
+                        ToolCallArgsEvent(
+                            type=EventType.TOOL_CALL_ARGS,
+                            tool_call_id=tool_call_id,
+                            delta=delta,
+                            raw_event=event,
+                        )
+                    )
+                    super()._dispatch_event(
+                        ToolCallEndEvent(
+                            type=EventType.TOOL_CALL_END,
+                            tool_call_id=tool_call_id,
+                            raw_event=event,
+                        )
+                    )
+                    end_dispatched = True
+                except Exception:
+                    if dispatched_start and not end_dispatched:
+                        try:
+                            super()._dispatch_event(
+                                ToolCallEndEvent(
+                                    type=EventType.TOOL_CALL_END,
+                                    tool_call_id=tool_call_id,
+                                    raw_event=event,
+                                )
+                            )
+                        except Exception:
+                            logger.error(
+                                "Failed to emit compensating TOOL_CALL_END for %s",
+                                tool_call_id,
+                                exc_info=True,
+                            )
+                    raise
                 return super()._dispatch_event(event)
 
             if custom_event.name == CustomEventNames.ManuallyEmitState.value:
@@ -234,5 +291,8 @@ class LangGraphAGUIAgent(LangGraphAgent):
 
     def dict_repr(self):
         """Return dictionary representation of the agent"""
-        super_repr = super().dict_repr()
-        return {**super_repr, "type": "langgraph_agui"}
+        return {
+            "name": self.name,
+            "description": self.description or "",
+            "type": "langgraph_agui",
+        }

{copilotkit-0.1.90 → copilotkit-0.1.92}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "copilotkit"
-version = "0.1.90"
+version = "0.1.92"
 description = "CopilotKit python SDK"
 authors = ["Markus Ecker <markus.ecker@gmail.com>"]
 license = "MIT"
@@ -48,4 +48,4 @@ requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
 [dependency-groups]
-dev = ["pytest (>=9.0.2,<10.0.0)"]
+dev = ["pytest (>=9.0.2,<10.0.0)", "pytest-asyncio (>=1.0.0,<2.0.0)"]

copilotkit-0.1.90/copilotkit/header_propagation.py

@@ -1,59 +0,0 @@
-"""Header propagation for forwarding x-* prefixed headers to outgoing LLM calls.
-
-Uses Python contextvars for per-request ambient state in async FastAPI handlers.
-An httpx event hook reads the ContextVar and injects headers on outgoing requests.
-Matches the CopilotKit runtime's extractForwardableHeaders() behavior.
-"""
-
-import contextvars
-import warnings
-from typing import Dict
-
-# Ambient per-request state for headers to forward to LLM calls
-_forwarded_headers: contextvars.ContextVar[Dict[str, str]] = contextvars.ContextVar(
-    "copilotkit_forwarded_headers"
-)
-
-
-def set_forwarded_headers(headers: Dict[str, str]) -> None:
-    """Store headers to forward to outgoing LLM calls.
-    Filters to x-* prefixed headers only."""
-    filtered = {k.lower(): v for k, v in headers.items() if k.lower().startswith("x-")}
-    _forwarded_headers.set(filtered)
-
-
-def get_forwarded_headers() -> Dict[str, str]:
-    """Get headers that should be forwarded to outgoing LLM calls."""
-    return _forwarded_headers.get({})
-
-
-def install_httpx_hook(client) -> None:
-    """Append an event hook to an httpx client that injects forwarded headers.
-
-    Works with OpenAI and Anthropic Python SDKs (both use httpx internally).
-    No-op when no headers are set (demo traffic).
-
-    Parameters
-    ----------
-    client : object
-        An OpenAI/Anthropic client instance, or a raw httpx.Client/AsyncClient.
-        For SDK clients the underlying transport lives at ``client._client``.
-    """
-
-    def _inject_headers(request):
-        headers = get_forwarded_headers()
-        for key, value in headers.items():
-            request.headers[key] = value
-
-    # OpenAI / Anthropic SDKs wrap an httpx client at client._client
-    if hasattr(client, "_client") and hasattr(client._client, "event_hooks"):
-        client._client.event_hooks["request"].append(_inject_headers)
-    elif hasattr(client, "event_hooks"):
-        # Raw httpx.Client / httpx.AsyncClient
-        client.event_hooks["request"].append(_inject_headers)
-    else:
-        warnings.warn(
-            f"install_httpx_hook: client of type {type(client).__name__} has no "
-            "recognized event_hooks attribute; x-* headers will not be forwarded",
-            stacklevel=2,
-        )