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

{agent_framework_github_copilot-2.1.0 → 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.0
+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
@@ -46,7 +57,8 @@ When you register a `FunctionTool` declared with `approval_mode="always_require"
 do **not** supply your own `on_pre_tool_use` hook, `GitHubCopilotAgent` installs a default
 `on_pre_tool_use` hook that returns `"ask"` for that tool and defers (`None`) for all other
 tools. The `"ask"` decision routes to your `on_permission_request` handler, where you
-approve or deny the call:
+approve or deny the call. Other session hooks, such as `on_post_tool_use` or
+`on_session_start`, are preserved alongside this default approval hook:
 
 ```python
 from agent_framework import tool
@@ -83,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
@@ -97,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`
 
@@ -142,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.0 → 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
@@ -20,7 +31,8 @@ When you register a `FunctionTool` declared with `approval_mode="always_require"
 do **not** supply your own `on_pre_tool_use` hook, `GitHubCopilotAgent` installs a default
 `on_pre_tool_use` hook that returns `"ask"` for that tool and defers (`None`) for all other
 tools. The `"ask"` decision routes to your `on_permission_request` handler, where you
-approve or deny the call:
+approve or deny the call. Other session hooks, such as `on_post_tool_use` or
+`on_session_start`, are preserved alongside this default approval hook:
 
 ```python
 from agent_framework import tool
@@ -57,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
@@ -71,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`
 
@@ -116,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.0 → 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
@@ -1505,17 +1476,16 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
         ``approval_mode="always_require"`` is delegated to the Copilot SDK's native
         ``on_pre_tool_use`` hook:
 
-        - If the caller supplies their own session hooks -- either the SDK-native
-          ``hooks`` dict or the convenience ``on_pre_tool_use`` handler (via per-run
-          ``options`` or ``default_options``) -- those take precedence and are used
-          as-is. When both are given, the explicit ``hooks`` dict wins for any key it
-          defines and the ``on_pre_tool_use`` shortcut fills in that key otherwise. A
-          warning is logged naming any approval-required tool that will therefore not
-          be automatically gated, since the caller's hooks are responsible for
-          enforcing approval.
+        - If the caller supplies their own ``on_pre_tool_use`` handler -- either in
+          the SDK-native ``hooks`` dict or through the convenience option (via per-run
+          ``options`` or ``default_options``) -- it takes precedence. When both are
+          given, the explicit ``hooks`` dict wins for any key it defines and the
+          shortcut fills in that key otherwise. A warning names any approval-required
+          tool that the caller's pre-tool-use handler is responsible for gating.
         - Otherwise, when any approval-required tool is present, a default hook is
           installed that returns ``"ask"`` for those tools (routing the decision to
           ``on_permission_request``) and defers (``None``) for all other tools.
+          Unrelated caller hooks are preserved and do not replace this default.
         - The default hook is **not** installed when the deprecated
           ``on_function_approval`` callback is configured: in that case approval is
           enforced inside the tool handler (see :meth:`_tool_to_copilot_tool`) to
@@ -1532,12 +1502,12 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             The hooks to register for the session, or ``None`` if none are needed.
         """
         user_hook: PreToolUseHandler | None = options.get("on_pre_tool_use") or self._on_pre_tool_use
-        caller_hooks: Mapping[str, Any] | None = options.get("hooks")
+        caller_hooks: SessionHooks | None = options.get("hooks")
 
         # Combine caller-provided hooks: the SDK-native ``hooks`` dict plus the
         # convenience ``on_pre_tool_use`` shortcut. The explicit dict wins for the
         # keys it defines; the shortcut only fills in ``on_pre_tool_use`` otherwise.
-        combined: dict[str, Any] = {}
+        combined: SessionHooks = {}
         if user_hook is not None:
             combined["on_pre_tool_use"] = user_hook
         if caller_hooks:
@@ -1547,7 +1517,7 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
             tool.name for tool in all_tools if isinstance(tool, FunctionTool) and tool.approval_mode == "always_require"
         }
 
-        if combined:
+        if combined.get("on_pre_tool_use") is not None:
             if approval_required_names:
                 logger.warning(
                     "Custom session hooks are configured, so %d approval-required tool(s) (%s) "
@@ -1556,15 +1526,15 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
                     len(approval_required_names),
                     ", ".join(sorted(approval_required_names)),
                 )
-            return cast("SessionHooks", combined)
+            return combined
 
         if not approval_required_names:
-            return None
+            return combined or None
 
         # The deprecated on_function_approval callback enforces approval in the tool
         # handler; don't also install the default ask-hook (which would double-gate).
         if self._function_approval_handler is not None:
-            return None
+            return combined or None
 
         def default_pre_tool_use(
             hook_input: Mapping[str, Any],
@@ -1580,7 +1550,8 @@ class RawGitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
                 }
             return None
 
-        return {"on_pre_tool_use": default_pre_tool_use}
+        combined["on_pre_tool_use"] = default_pre_tool_use
+        return combined
 
     def _session_run_lock(self, service_session_id: str) -> asyncio.Lock:
         """Return the lock that serializes runs on one Copilot service session."""
@@ -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.0 → 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.0"
+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]