open-edison 0.1.17__py3-none-any.whl → 0.1.26__py3-none-any.whl

{open_edison-0.1.17.dist-info → open_edison-0.1.26.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-edison
-Version: 0.1.17
+Version: 0.1.26
 Summary: Open-source MCP security, aggregation, and monitoring. Single-user, self-hosted MCP proxy.
 Author-email: Hugo Berg <hugo@edison.watch>
 License-File: LICENSE
@@ -25,11 +25,42 @@ Requires-Dist: pytest>=8.3.3; extra == 'dev'
 Requires-Dist: ruff>=0.12.3; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# OpenEdison
+# OpenEdison 🔒⚡️
 
-Open-source MCP security gateway that prevents data exfiltration—via direct access or tool chaining—with full monitoring for local single‑user deployments. Provides core functionality of <https://edison.watch> for local, single-user use.
+MCP security gateway that prevents data exfiltration—via direct access or tool chaining—with full monitoring for local single‑user deployments. Provides core functionality of <https://edison.watch> for local use.
 
-Just want to run it?
+<p align="center">
+  <img src="media/trifecta520p.gif" alt="Trifecta Security Risk Animation" width="520">
+</p>
+
+<div align="center">
+  <h2>📧 To get visibility, control and exfiltration blocker into AI's interaction with your company software, systems of record, DBs, <a href="mailto:hello@edison.watch">Contact us</a> to discuss.</h2>
+</div>
+
+<p align="center">
+  <img alt="Project Version" src="https://img.shields.io/pypi/v/open-edison?label=version&color=blue">
+  <img alt="Python Version" src="https://img.shields.io/badge/python-3.12-blue?logo=python">
+  <img src="https://img.shields.io/badge/License-GPLv3-blue" alt="License">
+
+
+</p>
+
+--- 
+
+
+## Features ✨
+
+- 🛑 **Prevent Data Leaks** - Edison automatically blocks any data leaks, even if your AI gets jailbroken
+- 👤 **Single-user MCP proxy** - No multi-user complexity, just a simple proxy for your MCP servers
+- 🗂️ **JSON configuration** - Easy to configure and manage your MCP servers
+- 🖥️ **Simple local frontend** - Track and monitor your MCP interactions, servers, and sessions.
+- 📊 **Session tracking** - Track and monitor your MCP interactions
+- 🔗 **Simple API** - REST API for managing MCP servers and proxying requests
+- 🐳 **Docker support** - Run in a container for easy deployment
+
+## Quick Start 🚀
+
+The fastest way to get started:
 
 ```bash
 # Installs uv (via Astral installer) and launches open-edison with uvx.
@@ -39,36 +70,31 @@ curl -fsSL https://raw.githubusercontent.com/Edison-Watch/open-edison/main/curl_
 
 Run locally with uvx: `uvx open-edison --config-dir ~/edison-config`
 
+<details>
+<summary>⬇️ Install Node.js/npm (optional for MCP tools)</summary>
+
 If you need `npx` (for Node-based MCP tools like `mcp-remote`), install Node.js as well:
 
-- macOS:
-  - uv: `curl -fsSL https://astral.sh/uv/install.sh | sh`
-  - Node/npx: `brew install node`
-- Linux (Debian/Ubuntu):
-  - uv: `curl -fsSL https://astral.sh/uv/install.sh | sh`
-  - Node/npx: `sudo apt-get update && sudo apt-get install -y nodejs npm`
-- Windows (PowerShell):
-  - uv: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
-  - Node/npx: `winget install -e --id OpenJS.NodeJS`
+![macOS](https://img.shields.io/badge/mac%20os-000000?style=for-the-badge&logo=apple&logoColor=white)
 
-After installation, ensure that `npx` is available on PATH.
+- uv: `curl -fsSL https://astral.sh/uv/install.sh | sh`
+- Node/npx: `brew install node`
 
-<div align="center">
-  <h2>📧 Interested in connecting AI to your business software with proper access controls? <a href="mailto:hello@edison.watch">Contact us</a> to discuss.</h2>
-</div>
+![Linux](https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black)
+
+- uv: `curl -fsSL https://astral.sh/uv/install.sh | sh`
+- Node/npx: `sudo apt-get update && sudo apt-get install -y nodejs npm`
 
-## Features
+![Windows](https://img.shields.io/badge/Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white)
 
-- **Single-user MCP proxy** - No multi-user complexity, just a simple proxy for your MCP servers
-- **JSON configuration** - Easy to configure and manage your MCP servers
-- **Simple local frontend** - Track and monitor your MCP interactions, servers, and sessions.
-- **Session tracking** - Track and monitor your MCP interactions
-- **Simple API** - REST API for managing MCP servers and proxying requests
-- **Docker support** - Run in a container for easy deployment
+- uv: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
+- Node/npx: `winget install -e --id OpenJS.NodeJS`
 
-## Quick Start
+After installation, ensure that `npx` is available on PATH.
+</details>
 
-### Install from PyPI
+<details>
+<summary><img src="https://img.shields.io/badge/pypi-3775A9?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"> Install from PyPI</summary>
 
 #### Prerequisites
 
@@ -91,31 +117,37 @@ open-edison run --config-dir ~/edison-config
 OPEN_EDISON_CONFIG_DIR=~/edison-config open-edison run
 ```
 
-### Run with Docker
+</details>
+
+<details>
+<summary><img src="https://img.shields.io/badge/Docker-2CA5E0?style=for-the-badge&logo=docker&logoColor=white" alt="Docker"> Run with Docker</summary>
 
 There is a dockerfile for simple local setup.
 
 ```bash
 # Single-line:
-git clone https://github.com/GatlingX/open-edison.git && cd open-edison && make docker_run
+git clone https://github.com/Edison-Watch/open-edison.git && cd open-edison && make docker_run
 
 # Or
 # Clone repo
-git clone https://github.com/GatlingX/open-edison.git
+git clone https://github.com/Edison-Watch/open-edison.git
 # Enter repo
 cd open-edison
 # Build and run
 make docker_run
 ```
 
-The MCP server will be available at `http://localhost:3000` and the api + frontend at `http://localhost:3001`.
+The MCP server will be available at `http://localhost:3000` and the api + frontend at `http://localhost:3001`. 🌐
 
-### Run from source
+</details>
+
+<details>
+<summary>⚙️ Run from source</summary>
 
 1. Clone the repository:
 
 ```bash
-git clone https://github.com/GatlingX/open-edison.git
+git clone https://github.com/Edison-Watch/open-edison.git
 cd open-edison
 ```
 
@@ -146,9 +178,12 @@ make run
 open-edison run
 ```
 
-The server will be available at `http://localhost:3000`.
+The server will be available at `http://localhost:3000`. 🌐
+
+</details>
 
-## MCP Connection
+<details>
+<summary>🔌 MCP Connection</summary>
 
 Connect any MCP client to Open Edison (requires Node.js/npm for `npx`):
 
@@ -169,19 +204,23 @@ Or add to your MCP client config:
 }
 ```
 
-## Usage
+</details>
+
+<details>
+<summary>🧭 Usage</summary>
 
 ### API Endpoints
 
 See [API Reference](docs/quick-reference/api_reference.md) for full API documentation.
 
-## Development
+<details>
+<summary>🛠️ Development</summary>
 
-### Setup
+### Setup 🧰
 
 Setup from source as above.
 
-### Run
+### Run ▶️
 
 Server doesn't have any auto-reload at the moment, so you'll need to run & ctrl-c this during development.
 
@@ -189,7 +228,7 @@ Server doesn't have any auto-reload at the moment, so you'll need to run & ctrl-
 make run
 ```
 
-### Tests/code quality
+### Tests/code quality ✅
 
 We expect `make ci` to return cleanly.
 
@@ -197,7 +236,12 @@ We expect `make ci` to return cleanly.
 make ci
 ```
 
-## Configuration
+</details>
+
+<details>
+<summary>⚙️ Configuration (config.json)</summary>
+
+## Configuration ⚙️
 
 The `config.json` file contains all configuration:
 
@@ -215,21 +259,32 @@ Each MCP server configuration includes:
 - `env` - Environment variables (optional)
 - `enabled` - Whether to auto-start this server
 
-## Security & Permissions System
+</details>
 
-Open Edison includes a comprehensive security monitoring system that tracks the "lethal trifecta" of AI agent risks:
+</details>
+
+## 🔐 How Edison prevents data leakages
+
+<details>
+<summary>🔱 The lethal trifecta, agent lifecycle management</summary>
+
+Open Edison includes a comprehensive security monitoring system that tracks the "lethal trifecta" of AI agent risks, as described in [Simon Willison's blog post](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/):
+
+<img src="media/lethal-trifecta.png" alt="The lethal trifecta diagram showing the three key AI agent security risks" width="70%">
 
 1. **Private data access** - Access to sensitive local files/data
 2. **Untrusted content exposure** - Exposure to external/web content  
 3. **External communication** - Ability to write/send data externally
 
+<img src="media/pam-diagram.png" alt="Privileged Access Management (PAM) example showing the lethal trifecta in action" width="90%">
+
 The configuration allows you to classify these risks across **tools**, **resources**, and **prompts** using separate configuration files.
 
 In addition to trifecta, we track Access Control Level (ACL) for each tool call,
 that is, each tool has an ACL level (one of PUBLIC, PRIVATE, or SECRET), and we track the highest ACL level for each session.
 If a write operation is attempted to a lower ACL level, it is blocked.
 
-### Tool Permissions (`tool_permissions.json`)
+### 🧰 Tool Permissions (`tool_permissions.json`)
 
 Defines security classifications for MCP tools. See full file: [tool_permissions.json](tool_permissions.json), it looks like:
 
@@ -246,6 +301,9 @@ Defines security classifications for MCP tools. See full file: [tool_permissions
 }
 ```
 
+<details>
+<summary>📁 Resource Permissions (`resource_permissions.json`)</summary>
+
 ### Resource Permissions (`resource_permissions.json`)
 
 Defines security classifications for resource access patterns. See full file: [resource_permissions.json](resource_permissions.json), it looks like:
@@ -257,6 +315,11 @@ Defines security classifications for resource access patterns. See full file: [r
 }
 ```
 
+</details>
+
+<details>
+<summary>💬 Prompt Permissions (`prompt_permissions.json`)</summary>
+
 ### Prompt Permissions (`prompt_permissions.json`)
 
 Defines security classifications for prompt types. See full file: [prompt_permissions.json](prompt_permissions.json), it looks like:
@@ -268,7 +331,9 @@ Defines security classifications for prompt types. See full file: [prompt_permis
 }
 ```
 
-### Wildcard Patterns
+</details>
+
+### Wildcard Patterns ✨
 
 All permission types support wildcard patterns:
 
@@ -276,21 +341,29 @@ All permission types support wildcard patterns:
 - **Resources**: `scheme:*` (e.g., `file:*` matches all file resources)  
 - **Prompts**: `type:*` (e.g., `template:*` matches all template prompts)
 
-### Security Monitoring
+### Security Monitoring 🕵️
 
 **All items must be explicitly configured** - unknown tools/resources/prompts will be rejected for security.
 
 Use the `get_security_status` tool to monitor your session's current risk level and see which capabilities have been accessed. When the lethal trifecta is achieved (all three risk flags set), further potentially dangerous operations are blocked.
 
-## Documentation
+</details>
+
+
+
+## Documentation 📚
 
 📚 **Complete documentation available in [`docs/`](docs/)**
 
-- **[Getting Started](docs/quick-reference/config_quick_start.md)** - Quick setup guide
-- **[Configuration](docs/core/configuration.md)** - Complete configuration reference
-- **[API Reference](docs/quick-reference/api_reference.md)** - REST API documentation
-- **[Development Guide](docs/development/development_guide.md)** - Contributing and development
+- 🚀 **[Getting Started](docs/quick-reference/config_quick_start.md)** - Quick setup guide
+- ⚙️ **[Configuration](docs/core/configuration.md)** - Complete configuration reference
+- 📡 **[API Reference](docs/quick-reference/api_reference.md)** - REST API documentation
+- 🧑‍💻 **[Development Guide](docs/development/development_guide.md)** - Contributing and development
 
-## License
+
+<details>
+<summary>📄 License</summary>
 
 GPL-3.0 License - see [LICENSE](LICENSE) for details.
+
+</details>

open_edison-0.1.26.dist-info/RECORD

@@ -0,0 +1,17 @@
+src/__init__.py,sha256=QWeZdjAm2D2B0eWhd8m2-DPpWvIP26KcNJxwEoU1oEQ,254
+src/__main__.py,sha256=kQsaVyzRa_ESC57JpKDSQJAHExuXme0rM5beJsYxFeA,161
+src/cli.py,sha256=_F1xtUU2h4snWUHf1NptRWGQaD2OSIhEPGLh9Rzmtis,10032
+src/config.py,sha256=jZYX4q09hg2VlLCq7FIKa_bL7NpNNMStYMQyEMZPrDg,9910
+src/events.py,sha256=rBH7rnaSWZ7GIC8zyBTwpcvIKWmKYCki-DNGgJhxPow,5001
+src/oauth_manager.py,sha256=qcQa5BDRZr4bjqiXNflCnrXOh9mo9JVjvP2Caseg2Uc,9943
+src/permissions.py,sha256=kIbLPtaJAwV5CF-YECLhU7HEF704LdQCI2xIh-TCu4I,10834
+src/server.py,sha256=Gg2DnnvZr59e0PGtRXVD94fxVxtiNnizlIrVkeLGIok,44504
+src/single_user_mcp.py,sha256=bbWbuuBxjL0DJY9kAHtHt8jwQNePXPa4cD4gnbD9XmE,16897
+src/telemetry.py,sha256=-RZPIjpI53zbsKmp-63REeZ1JirWHV5WvpSRa2nqZEk,11321
+src/middleware/data_access_tracker.py,sha256=bArBffWgYmvxOx9z_pgXQhogvnWQcc1m6WvEblDD4gw,15039
+src/middleware/session_tracking.py,sha256=p3UMruIe5RBYnfAzmSaHMOeN3xKN-9EiCSd7nAGjgrw,22138
+open_edison-0.1.26.dist-info/METADATA,sha256=Tfw-vOv_KlIvUBMcU5DjwHNiksFxJejJBurC0dp_b4Q,11685
+open_edison-0.1.26.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+open_edison-0.1.26.dist-info/entry_points.txt,sha256=qNAkJcnoTXRhj8J--3PDmXz_TQKdB8H_0C9wiCtDIyA,72
+open_edison-0.1.26.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+open_edison-0.1.26.dist-info/RECORD,,

src/cli.py

@@ -177,6 +177,7 @@ def _spawn_frontend_dev(  # noqa: C901 - pragmatic complexity for env probing
 
 
 async def _run_server(args: Any) -> None:
+    # TODO check this works as we want it to
     # Resolve config dir and expose via env for the rest of the app
     config_dir_arg = getattr(args, "config_dir", None)
     if config_dir_arg is not None:
@@ -184,7 +185,7 @@ async def _run_server(args: Any) -> None:
     config_dir = get_config_dir()
 
     # Load config after setting env override
-    cfg = Config.load()
+    cfg = Config(config_dir)
 
     host = getattr(args, "host", None) or cfg.server.host
     port = getattr(args, "port", None) or cfg.server.port

src/config.py

@@ -58,12 +58,6 @@ def get_config_dir() -> Path:
         return (Path.home() / ".open-edison").resolve()
 
 
-# Back-compat private alias (internal modules may import this)
-def _get_config_dir() -> Path:  # noqa: D401
-    """Alias to public get_config_dir (maintained for internal imports)."""
-    return get_config_dir()
-
-
 def _default_config_path() -> Path:
     """Determine default config.json path.
 
@@ -75,22 +69,18 @@ def _default_config_path() -> Path:
     repo_config = root_dir / "config.json"
 
     # If pyproject.toml exists next to src/, we are likely in a repo checkout
+    # Prefer the user config directory if a config already exists there (runtime source of truth),
+    # otherwise fall back to the repo copy.
     if repo_pyproject.exists():
+        user_cfg = get_config_dir() / "config.json"
+        if user_cfg.exists():
+            return user_cfg
         return repo_config
 
-    # Otherwise, prefer user config directory
+    # Installed package: prefer user config directory
     return get_config_dir() / "config.json"
 
 
-class ConfigError(Exception):
-    """Exception raised for configuration-related errors"""
-
-    def __init__(self, message: str, config_path: Path | None = None):
-        self.message = message
-        self.config_path = config_path
-        super().__init__(self.message)
-
-
 @dataclass
 class ServerConfig:
     """Server configuration"""
@@ -119,10 +109,41 @@ class MCPServerConfig:
     enabled: bool = True
     roots: list[str] | None = None
 
+    oauth_scopes: list[str] | None = None
+    """OAuth scopes to request for this server."""
+
+    oauth_client_name: str | None = None
+    """Custom client name for OAuth registration."""
+
     def __post_init__(self):
         if self.env is None:
             self.env = {}
 
+    def is_remote_server(self) -> bool:
+        """
+        Check if this is a remote MCP server (connects to external HTTPS endpoint).
+
+        Remote servers use mcp-remote with HTTPS URLs and may require OAuth.
+        Local servers run as child processes and don't need OAuth.
+        """
+        return (
+            self.command == "npx"
+            and len(self.args) >= 3
+            and self.args[1] == "mcp-remote"
+            and self.args[2].startswith("https://")
+        )
+
+    def get_remote_url(self) -> str | None:
+        """
+        Get the remote URL for a remote MCP server.
+
+        Returns:
+            The HTTPS URL if this is a remote server, None otherwise
+        """
+        if self.is_remote_server():
+            return self.args[2]
+        return None
+
 
 @dataclass
 class TelemetryConfig:
@@ -160,8 +181,7 @@ class Config:
             log.warning(f"Failed to read version from pyproject.toml: {e}")
             return "unknown"
 
-    @classmethod
-    def load(cls, config_path: Path | None = None) -> "Config":
+    def __init__(self, config_path: Path | None = None) -> None:
         """Load configuration from JSON file.
 
         If a directory path is provided, will look for `config.json` inside it.
@@ -174,11 +194,12 @@ class Config:
             if config_path.is_dir():
                 config_path = config_path / "config.json"
 
+        log.info(f"Loading configuration from {config_path}")
+
         if not config_path.exists():
             log.warning(f"Config file not found at {config_path}, creating default config")
-            default_config = cls.create_default()
-            default_config.save(config_path)
-            return default_config
+            self.create_default()
+            self.save(config_path)
 
         with open(config_path) as f:
             data: dict[str, Any] = json.load(f)
@@ -216,15 +237,13 @@ class Config:
             export_interval_ms=export_interval_ms,
         )
 
-        return cls(
-            server=ServerConfig(**server_data),  # type: ignore
-            logging=LoggingConfig(**logging_data),  # type: ignore
-            mcp_servers=[
-                MCPServerConfig(**server_item)  # type: ignore
-                for server_item in mcp_servers_data  # type: ignore
-            ],
-            telemetry=telemetry_cfg,
-        )
+        self.server = ServerConfig(**server_data)  # type: ignore
+        self.logging = LoggingConfig(**logging_data)  # type: ignore
+        self.mcp_servers = [
+            MCPServerConfig(**server_item)  # type: ignore
+            for server_item in mcp_servers_data  # type: ignore
+        ]
+        self.telemetry = telemetry_cfg
 
     def save(self, config_path: Path | None = None) -> None:
         """Save configuration to JSON file"""
@@ -251,26 +270,19 @@ class Config:
 
         log.info(f"Configuration saved to {config_path}")
 
-    @classmethod
-    def create_default(cls) -> "Config":
+    def create_default(self) -> None:
         """Create default configuration"""
-        return cls(
-            server=ServerConfig(),
-            logging=LoggingConfig(),
-            mcp_servers=[
-                MCPServerConfig(
-                    name="filesystem",
-                    command="uvx",
-                    args=["mcp-server-filesystem", "/tmp"],
-                    enabled=False,
-                )
-            ],
-            telemetry=TelemetryConfig(
-                enabled=True,
-                otlp_endpoint=DEFAULT_OTLP_METRICS_ENDPOINT,
-            ),
+        self.server = ServerConfig()
+        self.logging = LoggingConfig()
+        self.mcp_servers = [
+            MCPServerConfig(
+                name="filesystem",
+                command="uvx",
+                args=["mcp-server-filesystem", "/tmp"],
+                enabled=False,
+            )
+        ]
+        self.telemetry = TelemetryConfig(
+            enabled=True,
+            otlp_endpoint=DEFAULT_OTLP_METRICS_ENDPOINT,
         )
-
-
-# Load global configuration
-config = Config.load()

src/events.py

@@ -0,0 +1,153 @@
+"""
+Lightweight in-process event broadcasting for Open Edison (SSE-friendly).
+
+Provides a simple publisher/subscriber model to stream JSON events to
+connected dashboard clients over Server-Sent Events (SSE).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator, Callable
+from functools import wraps
+from typing import Any
+
+from loguru import logger as log
+
+_subscribers: set[asyncio.Queue[str]] = set()
+_lock = asyncio.Lock()
+
+# One-time approvals for (session_id, kind, name)
+_approvals: dict[str, asyncio.Event] = {}
+_approvals_lock = asyncio.Lock()
+
+
+def _approval_key(session_id: str, kind: str, name: str) -> str:
+    return f"{session_id}::{kind}::{name}"
+
+
+def requires_loop(func: Callable[..., Any]) -> Callable[..., None | Any]:  # noqa: ANN401
+    """Decorator to ensure the function is called when there is an asyncio event loop.
+    This is for sync(!) functions that return None / can do so on error"""
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> None | Any:
+        if asyncio.get_event_loop_policy()._local._loop is None:  # type: ignore[attr-defined]
+            log.warning("fire_and_forget called in non-async context")
+            return None
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+async def subscribe() -> asyncio.Queue[str]:
+    """Register a new subscriber and return its queue of SSE strings."""
+    queue: asyncio.Queue[str] = asyncio.Queue(maxsize=100)
+    async with _lock:
+        _subscribers.add(queue)
+        log.debug(f"SSE subscriber added (total={len(_subscribers)})")
+    return queue
+
+
+async def unsubscribe(queue: asyncio.Queue[str]) -> None:
+    """Remove a subscriber and drain its queue."""
+    async with _lock:
+        _subscribers.discard(queue)
+        log.debug(f"SSE subscriber removed (total={len(_subscribers)})")
+    try:
+        while not queue.empty():
+            _ = queue.get_nowait()
+    except Exception:
+        pass
+
+
+async def publish(event: dict[str, Any]) -> None:
+    """Publish a JSON event to all subscribers.
+
+    The event is serialized and wrapped as an SSE data frame.
+    """
+    try:
+        data = json.dumps(event, ensure_ascii=False)
+    except Exception as e:  # noqa: BLE001
+        log.error(f"Failed to serialize event for SSE: {e}")
+        return
+
+    frame = f"data: {data}\n\n"
+    async with _lock:
+        dead: list[asyncio.Queue[str]] = []
+        for q in _subscribers:
+            try:
+                # Best-effort non-blocking put; drop if full to avoid backpressure
+                if q.full():
+                    _ = q.get_nowait()
+                q.put_nowait(frame)
+            except Exception:
+                dead.append(q)
+        for q in dead:
+            _subscribers.discard(q)
+
+
+@requires_loop
+def fire_and_forget(event: dict[str, Any]) -> None:
+    """Schedule publish(event) and log any exception when the task completes."""
+    task = asyncio.create_task(publish(event))
+
+    def _log_exc(t: asyncio.Task[None]) -> None:
+        try:
+            _ = t.exception()
+            if _ is not None:
+                log.error(f"SSE publish failed: {_}")
+        except Exception as e:  # noqa: BLE001
+            log.error(f"SSE publish done-callback error: {e}")
+
+    task.add_done_callback(_log_exc)
+
+
+async def approve_once(session_id: str, kind: str, name: str) -> None:
+    """Approve a single pending operation for this session/kind/name.
+
+    This unblocks exactly one waiter if present (and future waiters will create a new Event).
+    """
+    key = _approval_key(session_id, kind, name)
+    async with _approvals_lock:
+        ev = _approvals.get(key)
+        if ev is None:
+            ev = asyncio.Event()
+            _approvals[key] = ev
+        ev.set()
+
+
+async def wait_for_approval(session_id: str, kind: str, name: str, timeout_s: float = 30.0) -> bool:
+    """Wait up to timeout for approval. Consumes the approval if granted."""
+    key = _approval_key(session_id, kind, name)
+    async with _approvals_lock:
+        ev = _approvals.get(key)
+        if ev is None:
+            ev = asyncio.Event()
+            _approvals[key] = ev
+    try:
+        await asyncio.wait_for(ev.wait(), timeout=timeout_s)
+        return True
+    except TimeoutError:
+        return False
+    finally:
+        # Consume the event so it does not auto-approve future waits
+        async with _approvals_lock:
+            _approvals.pop(key, None)
+
+
+async def sse_stream(queue: asyncio.Queue[str]) -> AsyncIterator[bytes]:
+    """Yield SSE frames from the given queue with periodic heartbeats."""
+    try:
+        # Initial comment to open the stream
+        yield b": connected\n\n"
+        while True:
+            try:
+                frame = await asyncio.wait_for(queue.get(), timeout=15.0)
+                yield frame.encode("utf-8")
+            except TimeoutError:
+                # Heartbeat to keep the connection alive
+                yield b": ping\n\n"
+    finally:
+        await unsubscribe(queue)