agent-webui 2.6.3__tar.gz → 2.7.0__tar.gz

{agent_webui-2.6.3 → agent_webui-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-webui
-Version: 2.6.3
+Version: 2.7.0
 Summary: Agent Web Interface for Pydantic AI Agents
 Author-email: Repository Maintainers <maintainers@knuckles.team>
 License: MIT
@@ -12,34 +12,39 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: <3.15,>=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastapi>=0.139.2
-Requires-Dist: langfuse>=4.14.1
-Requires-Dist: pydantic-ai-slim[ui]>=2.14.1
-Requires-Dist: python-multipart>=0.0.20
-Requires-Dist: sse-starlette>=3.4.6
-Requires-Dist: starlette>=1.3.1
-Requires-Dist: uvicorn>=0.51.0
-Requires-Dist: watchfiles>=1.2.0
-Requires-Dist: logfire[fastapi,starlette]>=4.38.0
-Requires-Dist: joserfc>=1.7.4
+Requires-Dist: agent-utilities<4.0.0,>=3.0.0
+Requires-Dist: agent-connector-sdk<1.0.0,>=0.2.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: msgpack>=1.1.0
+Requires-Dist: fastapi>=0.143.3
+Requires-Dist: langfuse>=5.0.2
+Requires-Dist: pydantic-ai-slim[ui]==2.57.0
+Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: sse-starlette>=3.5.0
+Requires-Dist: starlette>=1.8.0
+Requires-Dist: uvicorn>=0.54.0
+Requires-Dist: watchfiles>=1.3.0
+Requires-Dist: logfire[fastapi,starlette]>=5.2.0
+Requires-Dist: joserfc>=1.7.5
 Provides-Extra: test
 Requires-Dist: pytest-xdist>=3.8.0; extra == "test"
 Requires-Dist: pytest>=9.1.1; extra == "test"
 Requires-Dist: pytest-asyncio>=1.4.0; extra == "test"
 Requires-Dist: pytest-cov>=7.1.0; extra == "test"
-Requires-Dist: pytest-env>=1.7.0; extra == "test"
+Requires-Dist: pytest-env>=1.8.0; extra == "test"
 Requires-Dist: pytest-timeout>=2.4.0; extra == "test"
-Requires-Dist: networkx>=3.6.1; extra == "test"
+Requires-Dist: pytest-randomly>=4.0.1; extra == "test"
+Requires-Dist: pytest-repeat>=0.9.4; extra == "test"
+Requires-Dist: networkx>=3.7; extra == "test"
 Requires-Dist: opentelemetry-instrumentation-starlette>=0.65b0; extra == "test"
 Requires-Dist: opentelemetry-instrumentation-fastapi>=0.65b0; extra == "test"
 Requires-Dist: opentelemetry-instrumentation-asgi>=0.65b0; extra == "test"
-Requires-Dist: agent-utilities[agent-headless,graph,graphos,metrics]>=2.0.0; extra == "test"
 Dynamic: license-file
 
-# Agent Web UI
+# Graph OS web UI
 
 <p align="center">
-  <img src="docs/assets/brands/agent-webui-logo-v1.png" alt="Agent Web UI logo" width="160" />
+  <img src="docs/assets/brands/agent-webui-logo-v1.png" alt="Graph OS Agent Web UI logo" width="160" />
 </p>
 
 <p align="center">
@@ -53,7 +58,7 @@ Dynamic: license-file
 [![Build](https://github.com/Knuckles-Team/agent-webui/actions/workflows/release.yml/badge.svg)](https://github.com/Knuckles-Team/agent-webui/actions/workflows/release.yml)
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-526cfe)](https://knuckles-team.github.io/agent-webui/)
 [![GitHub license](https://img.shields.io/github/license/Knuckles-Team/agent-webui)](LICENSE)
-[![Docs build](https://github.com/Knuckles-Team/agent-webui/actions/workflows/advisory.yml/badge.svg?branch=main)](https://github.com/Knuckles-Team/agent-webui/actions/workflows/advisory.yml)
+[![Docs build](https://github.com/Knuckles-Team/agent-webui/actions/workflows/pages.yml/badge.svg?branch=main)](https://github.com/Knuckles-Team/agent-webui/actions/workflows/pages.yml)
 [![PyPI - Downloads](https://img.shields.io/pypi/dd/agent-webui)](https://pypi.org/project/agent-webui/)
 [![PyPI - License](https://img.shields.io/pypi/l/agent-webui)](https://pypi.org/project/agent-webui/)
 [![PyPI - Wheel](https://img.shields.io/pypi/wheel/agent-webui)](https://pypi.org/project/agent-webui/)
@@ -83,7 +88,7 @@ Dynamic: license-file
 
 ## Overview
 
-Agent Web UI is the browser workspace composed by Graph OS. It brings agent
+Graph OS Agent Web UI is the browser workspace composed by Graph OS. It brings agent
 conversations, approvals, workflows, fleet activity, and Epistemic Graph
 exploration into one React application. Its FastAPI host keeps privileged
 credentials and gateway delegation on the server side.
@@ -92,7 +97,7 @@ credentials and gateway delegation on the server side.
 |---|---|
 | Browser presentation, local interaction state, accessible route composition, and the FastAPI boundary | Graph OS owns public routing, identity, policy, and fleet supervision; Agent Utilities owns agent behavior; Epistemic Graph owns durable knowledge; connector services own external-system effects |
 
-Current package Version: 2.6.3.
+Current package Version: 2.7.0.
 
 ## Key capabilities
 
@@ -121,7 +126,7 @@ then use the shared platform map to move between components:
 
 ## Architecture
 
-![Runtime architecture: people use Agent Web UI, Agent Terminal UI, Geniusbot, and Graph OS-hosted messaging; MCP, REST, and A2A clients enter through Graph OS; source systems flow through Agent Connector SDK into Epistemic Graph.](docs/assets/runtime-architecture.svg)
+![Runtime architecture: people use Agent Web UI, Agent Terminal UI, Geniusbot, and Graph OS-hosted messaging. MCP, REST, and A2A clients enter through Graph OS; source systems flow through Agent Connector SDK into Epistemic Graph.](https://raw.githubusercontent.com/Knuckles-Team/epistemic-graph/main/docs/assets/runtime-architecture.svg)
 
 People also enter through Agent Terminal UI and Geniusbot or Graph OS-hosted
 messaging; Agent Terminal UI exposes REST operations, with no ACP conversational
@@ -137,7 +142,7 @@ for the request flow and trust boundaries.
 
 ## Quick start
 
-Generate a local profile and launch Graph OS with Agent Web UI enabled:
+Generate a local profile and start Graph OS with Agent Web UI enabled:
 
 ```bash
 uvx --from "graph-os[webui]" setup-config generate --profile tiny
@@ -157,4 +162,4 @@ before opening a pull request.
 
 ## License
 
-Agent Web UI is available under the [MIT License](LICENSE).
+Graph OS Agent Web UI is available under the [MIT License](LICENSE).

{agent_webui-2.6.3 → agent_webui-2.7.0}/README.md

@@ -1,7 +1,7 @@
-# Agent Web UI
+# Graph OS web UI
 
 <p align="center">
-  <img src="docs/assets/brands/agent-webui-logo-v1.png" alt="Agent Web UI logo" width="160" />
+  <img src="docs/assets/brands/agent-webui-logo-v1.png" alt="Graph OS Agent Web UI logo" width="160" />
 </p>
 
 <p align="center">
@@ -15,7 +15,7 @@
 [![Build](https://github.com/Knuckles-Team/agent-webui/actions/workflows/release.yml/badge.svg)](https://github.com/Knuckles-Team/agent-webui/actions/workflows/release.yml)
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-526cfe)](https://knuckles-team.github.io/agent-webui/)
 [![GitHub license](https://img.shields.io/github/license/Knuckles-Team/agent-webui)](LICENSE)
-[![Docs build](https://github.com/Knuckles-Team/agent-webui/actions/workflows/advisory.yml/badge.svg?branch=main)](https://github.com/Knuckles-Team/agent-webui/actions/workflows/advisory.yml)
+[![Docs build](https://github.com/Knuckles-Team/agent-webui/actions/workflows/pages.yml/badge.svg?branch=main)](https://github.com/Knuckles-Team/agent-webui/actions/workflows/pages.yml)
 [![PyPI - Downloads](https://img.shields.io/pypi/dd/agent-webui)](https://pypi.org/project/agent-webui/)
 [![PyPI - License](https://img.shields.io/pypi/l/agent-webui)](https://pypi.org/project/agent-webui/)
 [![PyPI - Wheel](https://img.shields.io/pypi/wheel/agent-webui)](https://pypi.org/project/agent-webui/)
@@ -45,7 +45,7 @@
 
 ## Overview
 
-Agent Web UI is the browser workspace composed by Graph OS. It brings agent
+Graph OS Agent Web UI is the browser workspace composed by Graph OS. It brings agent
 conversations, approvals, workflows, fleet activity, and Epistemic Graph
 exploration into one React application. Its FastAPI host keeps privileged
 credentials and gateway delegation on the server side.
@@ -54,7 +54,7 @@ credentials and gateway delegation on the server side.
 |---|---|
 | Browser presentation, local interaction state, accessible route composition, and the FastAPI boundary | Graph OS owns public routing, identity, policy, and fleet supervision; Agent Utilities owns agent behavior; Epistemic Graph owns durable knowledge; connector services own external-system effects |
 
-Current package Version: 2.6.3.
+Current package Version: 2.7.0.
 
 ## Key capabilities
 
@@ -83,7 +83,7 @@ then use the shared platform map to move between components:
 
 ## Architecture
 
-![Runtime architecture: people use Agent Web UI, Agent Terminal UI, Geniusbot, and Graph OS-hosted messaging; MCP, REST, and A2A clients enter through Graph OS; source systems flow through Agent Connector SDK into Epistemic Graph.](docs/assets/runtime-architecture.svg)
+![Runtime architecture: people use Agent Web UI, Agent Terminal UI, Geniusbot, and Graph OS-hosted messaging. MCP, REST, and A2A clients enter through Graph OS; source systems flow through Agent Connector SDK into Epistemic Graph.](https://raw.githubusercontent.com/Knuckles-Team/epistemic-graph/main/docs/assets/runtime-architecture.svg)
 
 People also enter through Agent Terminal UI and Geniusbot or Graph OS-hosted
 messaging; Agent Terminal UI exposes REST operations, with no ACP conversational
@@ -99,7 +99,7 @@ for the request flow and trust boundaries.
 
 ## Quick start
 
-Generate a local profile and launch Graph OS with Agent Web UI enabled:
+Generate a local profile and start Graph OS with Agent Web UI enabled:
 
 ```bash
 uvx --from "graph-os[webui]" setup-config generate --profile tiny
@@ -119,4 +119,4 @@ before opening a pull request.
 
 ## License
 
-Agent Web UI is available under the [MIT License](LICENSE).
+Graph OS Agent Web UI is available under the [MIT License](LICENSE).

agent_webui-2.7.0/agent/agent_webui/__tests__/test_api_extensions.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+"""Test API endpoints for agent-webui backend."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from agent_webui.server import create_agent_web_app
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture
+def client(mock_agent, mock_workspace_helpers, authenticated_client_factory):
+    """Create test client.
+
+    ``create_agent_web_app`` installs ``WebUIActorIdentityMiddleware``
+    unconditionally, so every ``/api/*`` request now requires a verified
+    actor or is rejected 401 -- an unauthenticated ``TestClient`` no longer
+    reflects a real caller. ``authenticated_client_factory`` (tests/conftest
+    .py) presents a legitimate, fully verified admin credential through the
+    REAL identity + authorization middleware stack -- see its docstring and
+    ``authenticated_asgi_app`` for why this is not a bypass. Individual tests
+    that need to prove the gate itself (unauthenticated -> 401, an
+    under-privileged role -> 403) build their own client directly instead of
+    using this fixture -- see ``TestAuthenticationGateIsNotWeakened`` below.
+    """
+    app = create_agent_web_app(mock_agent, mock_workspace_helpers)
+    return authenticated_client_factory(app, raise_server_exceptions=False)
+
+
+class TestAuthenticationGateIsNotWeakened:
+    """Known-bad proof: the ``client`` fixture above now presents a
+    legitimate credential, but the gate it goes through must still reject
+    what it should. A gate never demonstrated against a known-bad input is
+    not evidence -- these drive the exact same real middleware stack through
+    a real ``TestClient``/ASGI request, not the fixture's happy-path
+    credential.
+    """
+
+    def test_unauthenticated_request_is_still_rejected(
+        self, mock_agent, mock_workspace_helpers
+    ):
+        """No credential at all -> 401, even though this file's default
+        ``client`` fixture now attaches one. Proves the fixture fix did not
+        weaken ``WebUIActorIdentityMiddleware``."""
+        app = create_agent_web_app(mock_agent, mock_workspace_helpers)
+        bare_client = TestClient(app, raise_server_exceptions=False)
+
+        response = bare_client.get('/api/enhanced/graph/stats')
+
+        assert response.status_code == 401
+        scope_response = bare_client.get('/api/enhanced/graph/graph3d/scope')
+        assert scope_response.status_code == 401
+
+    def test_underprivileged_role_is_still_refused_on_an_admin_route(
+        self, mock_agent, mock_workspace_helpers, authenticated_client_factory
+    ):
+        """A verified ``kg:read``-only caller must still be refused the
+        admin-only ``/api/enhanced/graph/query`` route (arbitrary Cypher
+        execution) -- the same boundary
+        ``test_security_boundaries.py::test_role_matrix_graph_query_post_stays_admin_only``
+        pins at the middleware-unit level; this proves it end to end through
+        a real ``TestClient`` request instead."""
+        app = create_agent_web_app(mock_agent, mock_workspace_helpers)
+        reader_client = authenticated_client_factory(
+            app, scope='kg:read', raise_server_exceptions=False
+        )
+
+        response = reader_client.post(
+            '/api/enhanced/graph/query', json={'query': 'MATCH (n) RETURN n'}
+        )
+
+        assert response.status_code == 403
+
+
+class TestGraphQueryEndpoint:
+    """Test Cypher query endpoint."""
+
+    def test_execute_cypher_dangerous_query(self, client):
+        """Test dangerous query rejection."""
+        dangerous_queries = [
+            {'query': 'DELETE n', 'params': {}},
+            {'query': 'DROP GRAPH', 'params': {}},
+            {'query': 'REMOVE n', 'params': {}},
+        ]
+
+        for query_data in dangerous_queries:
+            response = client.post('/api/enhanced/graph/query', json=query_data)
+            assert response.status_code == 400
+
+
+class TestCoverageExpansion:
+    """Additional tests for coverage expansion."""
+
+    def test_toggle_skill_success(self, client):
+        mock_toggle = MagicMock(return_value={'status': 'enabled'})
+        with patch('agent_webui.api_extensions.get_helper', return_value=mock_toggle):
+            response = client.post('/api/enhanced/skills/skill1/toggle')
+            assert response.status_code == 200
+            assert response.json()['status'] == 'enabled'
+
+
+class TestServerIntegration:
+    """Test server-level features."""
+
+    def test_spa_fallback(self, client):
+        response = client.get('/some-random-route')
+        assert response.status_code in [200, 404]

{agent_webui-2.6.3 → agent_webui-2.7.0}/agent/agent_webui/__tests__/test_bound_sweep_regressions.py

@@ -258,66 +258,6 @@ class TestTunnelHostsSlicesBeforeBounding:
         assert len(data['hosts']) == 256
 
 
-class TestGetAllTasksHandlesTheListOfPydanticModelsShape:
-    """A DIFFERENT root cause than the oversized-collection bug, found while
-    auditing it, but the SAME failure family: a shape mismatch upstream of
-    `_public_external_result` that this route's broad ``except`` turns into
-    an indistinguishable-from-empty ``{}``.
-
-    ``SDDManager.get_all_tasks()`` (``agent_utilities/sdd/__init__.py``)
-    returns ``list[Tasks]`` -- a bare Python ``list`` of pydantic models,
-    which itself has no ``.model_dump()`` (only each ELEMENT does). The
-    ``plan_id``-filtered branch's ``tasks.model_dump() if hasattr(tasks,
-    'model_dump') else tasks`` line never applied here (a bare ``list``
-    fails that ``hasattr`` check), so the raw list of pydantic objects
-    always reached ``_public_external_result`` unconverted --
-    `_bounded_external_value` cannot serialize a pydantic instance and
-    raises ``ValueError('...unsupported value')`` on ANY non-empty result,
-    not just an oversized one. The existing shared fixture
-    (``tests/conftest.py``'s ``mock_sdd_manager``) mocks
-    ``get_all_tasks.return_value`` as a single ``MagicMock(tasks=[])``,
-    which auto-satisfies ``hasattr(..., 'model_dump')`` and never exercised
-    the real ``list[Tasks]`` shape -- masking this from every existing test.
-    """
-
-    def test_survives_the_real_list_of_tasks_shape(self, client):
-        task_group = MagicMock()
-        task_group.model_dump.return_value = {
-            'feature_id': 'feature-1',
-            'tasks': [{'id': 't1', 'description': 'do the thing'}],
-        }
-        manager = MagicMock()
-        manager.get_all_tasks.return_value = [task_group]
-
-        with patch('agent_webui.api_extensions.SDDManager', return_value=manager):
-            response = client.get('/api/enhanced/sdd/tasks')
-
-        assert response.status_code == 200
-        data = response.json()
-        assert data == [
-            {
-                'feature_id': 'feature-1',
-                'tasks': [{'id': 't1', 'description': 'do the thing'}],
-            }
-        ]
-
-    def test_more_than_256_task_groups_is_sliced_not_raised(self, client):
-        groups = []
-        for i in range(300):
-            g = MagicMock()
-            g.model_dump.return_value = {'feature_id': f'feature-{i}', 'tasks': []}
-            groups.append(g)
-        manager = MagicMock()
-        manager.get_all_tasks.return_value = groups
-
-        with patch('agent_webui.api_extensions.SDDManager', return_value=manager):
-            response = client.get('/api/enhanced/sdd/tasks')
-
-        assert response.status_code == 200
-        data = response.json()
-        assert len(data) == 256
-
-
 class TestDockerContainersSlicesBeforeBounding:
     def test_more_than_256_containers_still_returns_the_capped_page(self, client):
         raw_containers = [

{agent_webui-2.6.3 → agent_webui-2.7.0}/agent/agent_webui/__tests__/test_browser_control.py

@@ -228,10 +228,8 @@ def _configure_identity(
     human: bool = True,
     allowed_origins: str = 'https://au.example',
 ) -> None:
-    import agent_utilities.security.request_identity as request_identity
-    from agent_utilities.core.config import config
-    from agent_utilities.security.actor_identity import ActorType
-    from agent_utilities.security.brain_context import ActorContext
+    from agent_webui import host
+    from agent_webui.host import ActorContext, config
 
     monkeypatch.setenv('WEBUI_SESSION_KEY', _SESSION_KEY)
     monkeypatch.setenv('WEBUI_OIDC_CLIENT_ID', 'agent-webui')
@@ -250,7 +248,7 @@ def _configure_identity(
     monkeypatch.setattr(config, 'allowed_origins', allowed_origins, raising=False)
     actor = ActorContext(
         actor_id='human-operator' if human else 'service-client',
-        actor_type=ActorType.HUMAN if human else ActorType.AUTOMATED_SERVICE,
+        actor_type='human' if human else 'automated_service',
         tenant_id='homelab',
         roles=('kg:read', 'kg:write'),
         authenticated=True,
@@ -260,9 +258,7 @@ def _configure_identity(
     async def actor_from_bearer_token(_token: str) -> ActorContext:
         return actor
 
-    monkeypatch.setattr(
-        request_identity, 'actor_from_bearer_token', actor_from_bearer_token
-    )
+    monkeypatch.setattr(host, 'verify_bearer', actor_from_bearer_token)
 
 
 def _app(

{agent_webui-2.6.3 → agent_webui-2.7.0}/agent/agent_webui/__tests__/test_chat_resource_routes.py

@@ -77,6 +77,20 @@ def _routes_by_path(app) -> dict[str, set[str]]:
     return out
 
 
+def _configure_verifier(patch: pytest.MonkeyPatch) -> None:
+    """The complete JWT verifier every WebUI listener requires."""
+    from agent_webui.host import config
+
+    patch.setattr(
+        config,
+        'auth_jwt_jwks_uri',
+        'https://idp.test/.well-known/jwks.json',
+        raising=False,
+    )
+    patch.setattr(config, 'auth_jwt_issuer', 'https://idp.test/', raising=False)
+    patch.setattr(config, 'auth_jwt_audience', 'agent-webui-test', raising=False)
+
+
 @pytest.fixture(autouse=True)
 def served_authority(monkeypatch):
     """Give the served boundary the audience + policy revision it requires.
@@ -86,41 +100,13 @@ def served_authority(monkeypatch):
     without both, which a bare test process has neither of. Setting them is
     part of standing the boundary up, not of weakening it.
     """
-    from agent_utilities.core.config import config
+    from agent_webui.host import config
 
-    monkeypatch.setattr(
-        config,
-        'auth_jwt_jwks_uri',
-        'https://idp.test/.well-known/jwks.json',
-        raising=False,
-    )
-    monkeypatch.setattr(config, 'auth_jwt_issuer', 'https://idp.test/', raising=False)
-    monkeypatch.setattr(config, 'auth_jwt_audience', 'agent-webui-test', raising=False)
+    # The complete JWT verifier comes from the shared autouse
+    # ``_complete_jwt_verifier`` fixture; the module-scoped app below
+    # configures its own (it is built before function-scoped fixtures run).
     monkeypatch.setattr(config, 'kg_policy_version', 'test-1', raising=False)
 
-    # Minting a real GraphSession performs a placement read against a live
-    # engine/coordinator, which a unit test process has none of. Project the
-    # verified actor into a session directly instead, exactly as
-    # ``test_mcp_delegation_routes.py`` does -- identity verification itself
-    # is exercised by the security-boundary suite; what this file pins is
-    # what happens AFTER an authenticated request is admitted.
-    from agent_utilities.knowledge_graph.core.session import GraphSession
-
-    def _session_for(actor: Any) -> GraphSession:
-        return GraphSession(
-            actor=actor,
-            tenant=str(actor.tenant_id or 'test-tenant'),
-            scopes=frozenset({'kg:read', 'kg:write', 'kg:admin'}),
-            graph='test-graph',
-            policy_version='test-1',
-            trace_context='chat-resource-routes-test',
-            audience='agent-webui-test',
-        )
-
-    monkeypatch.setattr(
-        'agent_utilities.security.request_identity.mint_graph_session', _session_for
-    )
-
 
 def _authenticated(app: Any) -> Any:
     """Wrap ``app`` so every request arrives with a verified admin identity.
@@ -151,8 +137,15 @@ def _authenticated(app: Any) -> Any:
 
 @pytest.fixture(scope='module')
 def app():
-    """The real FastAPI app, exactly as production builds it (no html_source)."""
-    return _build_app()
+    """The real FastAPI app, exactly as production builds it (no html_source).
+
+    Module-scoped, so it is built before the function-scoped verifier
+    fixtures run: it configures the complete JWT verifier every WebUI
+    listener requires itself.
+    """
+    with pytest.MonkeyPatch.context() as patch:
+        _configure_verifier(patch)
+        return _build_app()
 
 
 @pytest.fixture

{agent_webui-2.6.3 → agent_webui-2.7.0}/agent/agent_webui/__tests__/test_files_endpoints.py

@@ -21,8 +21,10 @@ from fastapi.testclient import TestClient
 
 
 def _make_client(mock_agent, helpers: dict) -> TestClient:
+    from _agent_webui_shared_fixtures import authenticated_asgi_app
+
     app = create_agent_web_app(mock_agent, helpers)
-    return TestClient(app, raise_server_exceptions=False)
+    return TestClient(authenticated_asgi_app(app), raise_server_exceptions=False)
 
 
 @pytest.fixture

agent_webui-2.7.0/agent/agent_webui/__tests__/test_host.py

@@ -0,0 +1,176 @@
+"""The host seam: settings, request grant, bearer parsing, served operations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from agent_webui import host
+from agent_webui.orchestrator_model import build_orchestrator_model
+from pydantic_ai.messages import ModelRequest, UserPromptPart
+from pydantic_ai.models.function import AgentInfo
+
+
+def _actor(**overrides: Any) -> host.ActorContext:
+    fields: dict[str, Any] = {
+        'actor_id': 'alice',
+        'tenant_id': 'acme',
+        'authenticated': True,
+    }
+    fields.update(overrides)
+    return host.ActorContext(**fields)
+
+
+class _FakeTransport:
+    def __init__(self, result: dict[str, Any]) -> None:
+        self.result = result
+        self.calls: list[tuple[str, dict[str, Any], str | None]] = []
+
+    async def invoke(self, op_id, params, *, idempotency_key=None):
+        self.calls.append((op_id, dict(params), idempotency_key))
+        return self.result
+
+
+def test_settings_read_environment_and_accept_overrides(monkeypatch) -> None:
+    monkeypatch.setenv('MAX_UPLOAD_SIZE', '2048')
+    monkeypatch.setenv('GATEWAY_RATE_LIMIT', 'not-a-number')
+    assert host.config.max_upload_size == 2048
+    assert host.config.gateway_rate_limit == 0.0
+    host.config.gateway_rate_limit = 5.0
+    assert host.config.gateway_rate_limit == 5.0
+    with pytest.raises(AttributeError):
+        host.config.no_such_field = 1
+
+
+@pytest.mark.parametrize(
+    ('roles', 'admins', 'expected'),
+    [
+        ((), '', {'kg:read'}),
+        (('kg:write',), '', {'kg:read', 'kg:write'}),
+        (('kg:admin',), '', {'kg:read', 'kg:write', 'kg:admin'}),
+        ((), 'alice', {'kg:read', 'kg:write', 'kg:admin'}),
+        (('unrelated',), 'bob', {'kg:read'}),
+    ],
+)
+def test_grant_scopes_are_hierarchical(monkeypatch, roles, admins, expected) -> None:
+    monkeypatch.setenv('KG_ADMIN_PRINCIPAL_IDS', admins)
+    grant = host.grant_for(_actor(roles=roles))
+    assert grant.scopes == expected
+    assert grant.tenant == 'acme'
+
+
+@pytest.mark.parametrize(
+    'actor',
+    [
+        _actor(authenticated=False),
+        _actor(tenant_id=''),
+        _actor(credential_expires_at=1),
+    ],
+)
+def test_grant_refuses_unverified_actors(actor) -> None:
+    with pytest.raises(PermissionError):
+        host.grant_for(actor)
+
+
+@pytest.mark.parametrize(
+    ('headers', 'expected'),
+    [
+        ([], None),
+        ([b'Bearer abc.def'], 'abc.def'),
+        ([b'bearer x'], 'x'),
+    ],
+)
+def test_bearer_parsing_accepts_one_credential(headers, expected) -> None:
+    assert host.parse_bearer_authorization(headers) == expected
+
+
+@pytest.mark.parametrize(
+    'headers',
+    [[b'Bearer a', b'Bearer b'], [b'Basic abc'], [b'Bearer '], [b'Bearer x' + b'\x7f']],
+)
+def test_bearer_parsing_refuses_ambiguous_credentials(headers) -> None:
+    with pytest.raises(PermissionError):
+        host.parse_bearer_authorization(headers)
+
+
+def test_actor_from_claims_projects_identity() -> None:
+    actor = host.actor_from_claims(
+        {
+            'sub': 'alice',
+            'tid': 'acme',
+            'email': 'alice@example.invalid',
+            'scope': 'kg:write extra',
+            'groups': ['ops'],
+            'realm_access': {'roles': ['kg:read']},
+            'exp': 4_102_444_800,
+        },
+        credential='token',
+    )
+    assert (actor.actor_id, actor.tenant_id, actor.actor_type) == (
+        'alice',
+        'acme',
+        'human',
+    )
+    assert {'kg:write', 'kg:read', 'ops'} <= set(actor.roles)
+    assert actor.groups == ('ops',)
+    assert actor.credential == 'token'
+    with pytest.raises(ValueError):
+        host.actor_from_claims({'tid': 'acme'})
+
+
+def test_current_actor_fails_closed_without_binding() -> None:
+    with pytest.raises(host.IdentityRequiredError):
+        host.current_actor()
+    with host.use_actor(_actor()) as bound:
+        assert host.current_actor() is bound
+
+
+async def test_verify_bearer_refuses_without_configured_verifier(monkeypatch) -> None:
+    monkeypatch.delenv('AUTH_JWT_JWKS_URI', raising=False)
+    host.config.reset()
+    with pytest.raises(host.TokenValidationError):
+        await host.verify_bearer('token')
+
+
+def test_unavailable_is_a_501_naming_the_operation() -> None:
+    error = host.unavailable('Graph browser', 'graph.nodes.list')
+    assert error.status_code == 501
+    assert error.detail['error'] == 'not_available'
+    assert error.detail['needs_operation'] == 'graph.nodes.list'
+
+
+async def test_invoke_operation_passes_the_idempotency_key() -> None:
+    transport = _FakeTransport({'value': {}})
+    await host.invoke_operation(
+        'agents.tasks.list', {'limit': 5}, transport=transport, idempotency_key='k1'
+    )
+    assert transport.calls == [('agents.tasks.list', {'limit': 5}, 'k1')]
+
+
+async def test_chat_turn_runs_through_served_agent_operation() -> None:
+    calls: list[tuple[str, dict[str, Any], str | None]] = []
+
+    async def invoke(op_id, params, *, idempotency_key=None):
+        calls.append((op_id, params, idempotency_key))
+        return {
+            'value': {
+                'status': {'message': {'parts': [{'kind': 'text', 'text': 'hi'}]}}
+            }
+        }
+
+    model = build_orchestrator_model(agent_name='helper', invoke=invoke)
+    messages = [ModelRequest(parts=[UserPromptPart(content='hello')])]
+    info = AgentInfo(
+        function_tools=[],
+        allow_text_output=True,
+        output_tools=[],
+        model_settings=None,
+        model_request_parameters=None,
+        instructions='be brief',
+    )
+    response = await model.function(messages, info)
+    assert response.parts[0].content == 'hi'
+    op_id, params, key = calls[0]
+    assert op_id == 'agents.run' and key
+    assert params['message']['parts'] == [{'kind': 'text', 'text': 'hello'}]
+    assert params['message']['metadata']['agent'] == 'helper'