agent-framework-github-copilot 2.1.1__tar.gz → 2.1.2__tar.gz

{agent_framework_github_copilot-2.1.1 → agent_framework_github_copilot-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-framework-github-copilot
-Version: 2.1.1
+Version: 2.1.2
 Summary: GitHub Copilot integration for Microsoft Agent Framework.
 Author-email: Microsoft <af-support@microsoft.com>
 Requires-Python: >=3.11
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.15
 Classifier: Typing :: Typed
 License-File: LICENSE
 Requires-Dist: agent-framework-core>=1.22.0,<2
-Requires-Dist: github-copilot-sdk>=1.0.16,<2.0; python_version >= '3.11'
+Requires-Dist: github-copilot-sdk>=1.0.16,<2.0
 Project-URL: homepage, https://aka.ms/agent-framework
 Project-URL: issues, https://github.com/microsoft/agent-framework/issues
 Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
@@ -36,6 +36,17 @@ pip install agent-framework-github-copilot
 
 The GitHub Copilot agent enables integration with GitHub Copilot, allowing you to interact with Copilot's agentic capabilities through the Agent Framework.
 
+## Context providers and function middleware
+
+Context providers can contribute messages, instructions, and tools to a run.
+`GitHubCopilotAgent` supports agent middleware, but the SDK owns its tool-calling loop
+and does not run Agent Framework function middleware. If a context provider contributes
+function middleware through `SessionContext.extend_middleware()`, the run raises
+`MiddlewareException` before creating or resuming an SDK session or registering its tools.
+This applies to both response modes and to `RawGitHubCopilotAgent`.
+
+Use `Agent` with a chat client when provider-contributed function middleware is required.
+
 ## Tool approval (`approval_mode="always_require"`)
 
 The GitHub Copilot SDK owns the tool-calling loop for this provider, so approval for
@@ -84,10 +95,9 @@ prompts) or a `domain` (URL prompts). Both are optional, so a bare
 `PermissionDecisionApproveForSession()` carries no scope at all and the Copilot CLI cannot
 interpret it.
 
-`GitHubCopilotAgent` therefore scopes such a decision automatically, using the request that
-triggered it — a shell prompt becomes an approval for that prompt's command identifiers, an
-MCP prompt an approval for that server and tool, a URL prompt an approval for that URL's
-domain, and so on:
+`GitHubCopilotAgent` therefore scopes such a decision automatically when the request provides
+a structured session approval — a shell prompt becomes an approval for that prompt's command
+identifiers, an MCP prompt an approval for that server and tool, and so on:
 
 ```python
 from copilot.generated.rpc import PermissionDecisionApproveForSession
@@ -98,12 +108,13 @@ def on_permission_request(request, invocation):
     return PermissionDecisionApproveForSession()
 ```
 
-The decision is only ever narrowed, never widened. When the prompt reports that it cannot
-offer session-scoped approval (`can_offer_session_approval=False`), or the request kind has
-no session-scoped approval at all (such as a `hook` prompt), the decision is downgraded to a
-single-use approval and a warning is logged. Pass an explicit `approval=` or `domain=` when
-you want to approve something other than the request being handled — decisions that already
-specify a scope are forwarded unchanged.
+The decision is only ever narrowed, never widened. A bare decision for a URL prompt is
+downgraded to a single-use approval because the framework cannot safely infer the Copilot
+CLI's exact URL permission scope. The same downgrade occurs when the prompt reports that it
+cannot offer session-scoped approval (`can_offer_session_approval=False`), or the request
+kind has no session-scoped approval at all (such as a `hook` prompt). A warning is logged in
+each case. Pass an explicit `approval=` or `domain=` when you want to approve a specific
+scope for the session — decisions that already specify a scope are forwarded unchanged.
 
 ### Deprecated: `on_function_approval`
 
@@ -143,4 +154,20 @@ directory that defines hooks it is not loading. See
 [`github_copilot_with_file_hooks.py`](../../samples/02-agents/providers/github_copilot/github_copilot_with_file_hooks.py)
 for a runnable example.
 
+## MCP configuration and session lifetime
+
+Constructor `default_options` provide SDK session defaults. Per-run `options` override
+the corresponding defaults for that request, including `mcp_servers`. Reusing an
+`AgentSession` with a `service_session_id` resumes SDK/CLI-owned service-session state.
+Forwarding a narrower MCP configuration, such as changing a server's `tools` from
+`["*"]` to `[]`, is not an authorization or revocation guarantee for capabilities
+already resident in that session. Enforce authorization at the MCP service/tool boundary.
+
+Use a fresh service session when narrowing configured capabilities: create
+`fresh_session = agent.create_session()`, then pass it to
+`await agent.run("Start a new conversation", session=fresh_session, options=restricted_options)`,
+where `restricted_options` contains the narrowed `mcp_servers` configuration.
+The new session has no `service_session_id`; do not copy the previous service-session
+state or reuse its SDK `session_id` in constructor or per-run options. A fresh session
+starts a new conversation rather than continuing the previous one.
 

{agent_framework_github_copilot-2.1.1 → agent_framework_github_copilot-2.1.2}/README.md

@@ -10,6 +10,17 @@ pip install agent-framework-github-copilot
 
 The GitHub Copilot agent enables integration with GitHub Copilot, allowing you to interact with Copilot's agentic capabilities through the Agent Framework.
 
+## Context providers and function middleware
+
+Context providers can contribute messages, instructions, and tools to a run.
+`GitHubCopilotAgent` supports agent middleware, but the SDK owns its tool-calling loop
+and does not run Agent Framework function middleware. If a context provider contributes
+function middleware through `SessionContext.extend_middleware()`, the run raises
+`MiddlewareException` before creating or resuming an SDK session or registering its tools.
+This applies to both response modes and to `RawGitHubCopilotAgent`.
+
+Use `Agent` with a chat client when provider-contributed function middleware is required.
+
 ## Tool approval (`approval_mode="always_require"`)
 
 The GitHub Copilot SDK owns the tool-calling loop for this provider, so approval for
@@ -58,10 +69,9 @@ prompts) or a `domain` (URL prompts). Both are optional, so a bare
 `PermissionDecisionApproveForSession()` carries no scope at all and the Copilot CLI cannot
 interpret it.
 
-`GitHubCopilotAgent` therefore scopes such a decision automatically, using the request that
-triggered it — a shell prompt becomes an approval for that prompt's command identifiers, an
-MCP prompt an approval for that server and tool, a URL prompt an approval for that URL's
-domain, and so on:
+`GitHubCopilotAgent` therefore scopes such a decision automatically when the request provides
+a structured session approval — a shell prompt becomes an approval for that prompt's command
+identifiers, an MCP prompt an approval for that server and tool, and so on:
 
 ```python
 from copilot.generated.rpc import PermissionDecisionApproveForSession
@@ -72,12 +82,13 @@ def on_permission_request(request, invocation):
     return PermissionDecisionApproveForSession()
 ```
 
-The decision is only ever narrowed, never widened. When the prompt reports that it cannot
-offer session-scoped approval (`can_offer_session_approval=False`), or the request kind has
-no session-scoped approval at all (such as a `hook` prompt), the decision is downgraded to a
-single-use approval and a warning is logged. Pass an explicit `approval=` or `domain=` when
-you want to approve something other than the request being handled — decisions that already
-specify a scope are forwarded unchanged.
+The decision is only ever narrowed, never widened. A bare decision for a URL prompt is
+downgraded to a single-use approval because the framework cannot safely infer the Copilot
+CLI's exact URL permission scope. The same downgrade occurs when the prompt reports that it
+cannot offer session-scoped approval (`can_offer_session_approval=False`), or the request
+kind has no session-scoped approval at all (such as a `hook` prompt). A warning is logged in
+each case. Pass an explicit `approval=` or `domain=` when you want to approve a specific
+scope for the session — decisions that already specify a scope are forwarded unchanged.
 
 ### Deprecated: `on_function_approval`
 
@@ -117,3 +128,19 @@ directory that defines hooks it is not loading. See
 [`github_copilot_with_file_hooks.py`](../../samples/02-agents/providers/github_copilot/github_copilot_with_file_hooks.py)
 for a runnable example.
 
+## MCP configuration and session lifetime
+
+Constructor `default_options` provide SDK session defaults. Per-run `options` override
+the corresponding defaults for that request, including `mcp_servers`. Reusing an
+`AgentSession` with a `service_session_id` resumes SDK/CLI-owned service-session state.
+Forwarding a narrower MCP configuration, such as changing a server's `tools` from
+`["*"]` to `[]`, is not an authorization or revocation guarantee for capabilities
+already resident in that session. Enforce authorization at the MCP service/tool boundary.
+
+Use a fresh service session when narrowing configured capabilities: create
+`fresh_session = agent.create_session()`, then pass it to
+`await agent.run("Start a new conversation", session=fresh_session, options=restricted_options)`,
+where `restricted_options` contains the narrowed `mcp_servers` configuration.
+The new session has no `service_session_id`; do not copy the previous service-session
+state or reuse its SDK `session_id` in constructor or per-run options. A fresh session
+starts a new conversation rather than continuing the previous one.

{agent_framework_github_copilot-2.1.1 → agent_framework_github_copilot-2.1.2}/agent_framework_github_copilot/_agent.py

@@ -21,8 +21,7 @@ from collections.abc import (
     Sequence,
 )
 from pathlib import Path
-from typing import Any, ClassVar, Generic, Literal, TypedDict, cast, overload
-from urllib.parse import urlparse
+from typing import Any, ClassVar, Generic, Literal, Self, TypedDict, cast, overload
 
 from agent_framework import (
     AgentMiddlewareLayer,
@@ -43,6 +42,7 @@ from agent_framework import (
     normalize_messages,
 )
 from agent_framework._mcp import MCPTool
+from agent_framework._middleware import categorize_middleware
 from agent_framework._settings import load_settings
 from agent_framework._telemetry import mark_feature_used
 from agent_framework._tools import FunctionTool, ToolTypes
@@ -51,15 +51,11 @@ from agent_framework._types import (
     _get_data_bytes_as_str,  # pyright: ignore[reportPrivateUsage]
     normalize_tools,
 )
-from agent_framework.exceptions import AgentException, ContentError
+from agent_framework.exceptions import AgentException, ContentError, MiddlewareException
 from agent_framework.observability import AgentTelemetryLayer
 
 from ._feature_usage import FeatureIndex
 
-if sys.version_info >= (3, 11):
-    from typing import Self  # pragma: no cover
-else:
-    from typing_extensions import Self  # pragma: no cover
 if sys.version_info >= (3, 13):
     from typing import TypeVar  # pragma: no cover
 else:
@@ -271,41 +267,6 @@ def _derive_session_approval(request: PermissionRequest) -> PermissionDecisionAp
     return None
 
 
-# Characters the WHATWG URL parser (used by the Copilot CLI) treats specially for
-# special-scheme URLs in ways that can move the authority boundary: backslashes are
-# normalized to forward slashes, and tabs/newlines/carriage returns are stripped before
-# parsing. Python's ``urlparse`` does none of this, so a URL containing any of them may
-# resolve to a different host than the CLI actually contacts.
-_WHATWG_AMBIGUOUS_URL_CHARS = ("\\", "\t", "\n", "\r")
-
-
-def _derive_url_session_domain(url: str) -> str | None:
-    """Return the domain to persist for a URL prompt, or ``None`` when it is unsafe to.
-
-    The persisted domain must match the host the Copilot CLI actually contacts, but the CLI
-    parses URLs with WHATWG semantics while this runs on Python's ``urlparse``. The two
-    disagree on crafted authorities -- a backslash before the ``@`` in
-    ``https://example.com<backslash>@evil.com`` resolves to ``example.com`` under the CLI
-    but ``evil.com`` under ``urlparse`` -- so trusting ``urlparse`` here could persist a
-    session-wide approval for an unrelated, attacker-chosen domain.
-
-    To keep the "narrow, never widen" guarantee, the domain is only returned when the URL
-    contains none of the characters the two parsers handle differently; any ambiguity (or a
-    URL with no derivable host) yields ``None`` so the caller can approve the single request
-    without persisting a domain.
-
-    Args:
-        url: The URL from the permission request.
-
-    Returns:
-        The lower-cased host to approve for the session, or ``None`` when the URL is
-        parser-ambiguous or has no host.
-    """
-    if any(char in url for char in _WHATWG_AMBIGUOUS_URL_CHARS):
-        return None
-    return urlparse(url).hostname or None
-
-
 def _normalize_permission_decision(
     decision: PermissionRequestResult,
     request: PermissionRequest,
@@ -317,11 +278,12 @@ def _normalize_permission_decision(
     is constructible with neither. That serializes to ``{"kind": "approve-for-session"}``,
     which the Copilot CLI cannot interpret -- it crashes with ``Cannot read properties of
     undefined (reading 'commandIdentifiers')``, taking the whole run down with it. This
-    reconstructs the intended scope from ``request``.
+    reconstructs structured tool scopes from ``request`` and narrows to a single request
+    when an exact session scope cannot be safely inferred.
 
-    The decision is only ever narrowed, never widened: when the prompt does not offer
-    session-scoped approval, or the request kind has no session approval representation,
-    the decision is downgraded to a single-use approval.
+    The decision is only ever narrowed, never widened: URL prompts, prompts that do not
+    offer session-scoped approval, and request kinds with no session approval representation
+    are downgraded to a single-use approval.
 
     Args:
         decision: The decision returned by the caller's permission handler.
@@ -339,14 +301,11 @@ def _normalize_permission_decision(
 
     try:
         if isinstance(request, PermissionRequestUrl):
-            domain = _derive_url_session_domain(request.url)
-            if domain:
-                return PermissionDecisionApproveForSession(domain=domain)
             logger.warning(
                 "Permission handler returned an unscoped 'approve-for-session' decision for a URL prompt, "
-                "but no unambiguous domain could be derived from '%s'. Approving this request only. Return "
+                "but Agent Framework cannot safely derive the Copilot CLI's exact URL permission scope. "
+                "Approving this request only. Return "
                 "PermissionDecisionApproveForSession(domain=...) to approve a domain for the session.",
-                request.url,
             )
             return PermissionDecisionApproveOnce()
 
@@ -895,6 +854,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
 
         Raises:
             AgentException: If the request fails.
+            MiddlewareException: If a context provider contributes unsupported function middleware.
         """
         if middleware:
             logger.warning(
@@ -1102,6 +1062,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
 
         Raises:
             AgentException: If the request fails.
+            MiddlewareException: If a context provider contributes unsupported function middleware.
         """
         if not self._started:
             await self.start()
@@ -1168,7 +1129,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
                         contents=[
                             Content.from_usage(
                                 usage_details,
-                                merge_mode="replace",
+                                merge_mode="append",
                                 raw_representation=event.data,
                             )
                         ]
@@ -1268,6 +1229,10 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
 
         Returns:
             The SessionContext with provider context populated.
+
+        Raises:
+            MiddlewareException: If a context provider contributes function middleware,
+                which cannot be applied to the SDK-owned tool loop.
         """
         session_context = SessionContext(
             session_id=session.session_id,
@@ -1286,6 +1251,12 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
                 state=session.state.setdefault(provider.source_id, {}),
             )
 
+        if categorize_middleware(session_context.get_middleware())["function"]:
+            raise MiddlewareException(
+                "GitHubCopilotAgent does not support function middleware contributed by context providers. "
+                "Use Agent with a chat client when function middleware is required."
+            )
+
         return session_context
 
     @staticmethod
@@ -1735,6 +1706,11 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         merged with the agent's tools and converted to SDK tools, and approval callbacks
         are turned into ``hooks``.
 
+        Forwarding options alone is not an authorization or revocation guarantee for
+        capabilities already resident in a resumed SDK/CLI service session. Enforce
+        authorization at the MCP service/tool boundary and use a fresh service session
+        when narrowing configured capabilities.
+
         Args:
             streaming: Whether to enable streaming for the session.
             runtime_options: Runtime options that take precedence over default_options.
@@ -1873,10 +1849,10 @@ class GitHubCopilotAgent(  # type: ignore[misc]
     RawGitHubCopilotAgent[OptionsT],
     Generic[OptionsT],
 ):
-    """A GitHub Copilot Agent with full middleware and telemetry support.
+    """A GitHub Copilot Agent with agent middleware and telemetry support.
 
     This is the recommended agent class for most use cases. It includes
-    middleware support and OpenTelemetry-based telemetry for observability,
+    agent middleware and OpenTelemetry-based telemetry for observability,
     with middleware running outside the telemetry span so middleware execution
     time is not captured in traces. For a minimal implementation without these
     layers, use :class:`RawGitHubCopilotAgent`.
@@ -1926,7 +1902,7 @@ class GitHubCopilotAgent(  # type: ignore[misc]
         env_file_path: str | None = None,
         env_file_encoding: str | None = None,
     ) -> None:
-        """Initialize a GitHub Copilot Agent with full middleware and telemetry.
+        """Initialize a GitHub Copilot Agent with agent middleware and telemetry.
 
         Args:
             instructions: System message for the agent.

{agent_framework_github_copilot-2.1.1 → agent_framework_github_copilot-2.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ description = "GitHub Copilot integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.11"
-version = "2.1.1"
+version = "2.1.2"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -24,7 +24,7 @@ classifiers = [
 ]
 dependencies = [
     "agent-framework-core>=1.22.0,<2",
-    "github-copilot-sdk>=1.0.16,<2.0; python_version >= '3.11'",
+    "github-copilot-sdk>=1.0.16,<2.0",
 ]
 
 [tool.uv]