connectonion 0.6.3__py3-none-any.whl → 0.6.5__py3-none-any.whl

connectonion/docs/useful_plugins/tool_approval.md

@@ -0,0 +1,139 @@
+# tool_approval
+
+Web-based approval for dangerous tools via WebSocket. Requires user confirmation before executing tools that can modify files or run commands.
+
+## Quick Start
+
+```python
+from connectonion import Agent, bash
+from connectonion.useful_plugins import tool_approval
+
+agent = Agent("assistant", tools=[bash], plugins=[tool_approval])
+agent.io = my_websocket_io  # Required for web mode
+
+agent.input("Install dependencies")
+# → Client receives: {"type": "approval_needed", "tool": "bash", "arguments": {"command": "npm install"}}
+# → Client responds: {"approved": true, "scope": "session"}
+# ✓ bash approved (session)
+```
+
+## How It Works
+
+1. Before each tool executes, check if it's dangerous
+2. If dangerous, send `approval_needed` event via WebSocket
+3. Wait for client response (blocks until received)
+4. If approved: execute tool, optionally remember for session
+5. If rejected: stop batch, return feedback to LLM
+
+## Tool Classification
+
+### Safe Tools (No Approval)
+
+Read-only operations that never modify state:
+
+```
+read, read_file, glob, grep, search
+list_files, get_file_info, task, load_guide
+enter_plan_mode, exit_plan_mode, write_plan
+task_output, ask_user
+```
+
+### Dangerous Tools (Require Approval)
+
+Operations that can modify files or have side effects:
+
+```
+bash, shell, run, run_in_dir
+write, edit, multi_edit
+run_background, kill_task
+send_email, post, delete, remove
+```
+
+## Client Protocol
+
+### Receive from server
+
+```json
+{
+  "type": "approval_needed",
+  "tool": "bash",
+  "arguments": {"command": "npm install"}
+}
+```
+
+### Send response
+
+```json
+// Approve for this session (no re-prompting)
+{"approved": true, "scope": "session"}
+
+// Approve once only
+{"approved": true, "scope": "once"}
+
+// Reject with feedback
+{"approved": false, "feedback": "Use yarn instead"}
+```
+
+## Approval Scopes
+
+| Scope | Behavior |
+|-------|----------|
+| `once` | Approve this call only |
+| `session` | Approve for rest of session (stored in memory) |
+
+## Rejection Behavior
+
+When user rejects a tool:
+
+1. Raises `ValueError` with feedback message
+2. Stops the entire tool batch (remaining tools skipped)
+3. LLM receives the error and can adjust approach
+
+```python
+# Example error message
+"User rejected tool 'bash'. Feedback: Use yarn instead"
+```
+
+## Terminal Logging
+
+The plugin logs all approval decisions:
+
+```
+✓ bash approved (session)    # Approved with session scope
+✓ edit approved (once)       # Approved for single use
+⏭ bash (session-approved)    # Skipped (already approved)
+✗ bash rejected: Use yarn    # Rejected with feedback
+✗ bash - connection closed   # WebSocket closed
+```
+
+## Events
+
+| Handler | Event | Purpose |
+|---------|-------|---------|
+| `check_approval` | `before_each_tool` | Check approval and prompt client |
+
+## Session Data
+
+```python
+# Approval state stored in session
+agent.current_session['approval'] = {
+    'approved_tools': {
+        'bash': 'session',   # Approved for session
+        'write': 'session'   # Approved for session
+    }
+}
+```
+
+## Non-Web Mode
+
+When `agent.io` is None (not web mode), all tools execute without approval. This is the default behavior for CLI usage.
+
+## Unknown Tools
+
+Tools not in SAFE_TOOLS or DANGEROUS_TOOLS are treated as safe and execute without approval.
+
+## See Also
+
+- [shell_approval](shell_approval.md) - Terminal-based approval for shell commands
+- [Events](../concepts/events.md) - Available event hooks
+- [Plugins](../concepts/plugins.md) - Plugin system overview

connectonion/network/__init__.py

@@ -4,7 +4,7 @@ LLM-Note:
   Dependencies: imports from [host/, io/, connect.py, relay.py, announce.py, trust/] | imported by [__init__.py main package, user code] | tested via submodule tests
   Data flow: pure re-export module aggregating networking functionality
   State/Effects: no state
-  Integration: exposes host(agent, port, trust), create_app(), IO/WebSocketIO, SessionStorage/Session, connect(url), RemoteAgent, Response, relay server (relay_connect, serve_loop), announce (create_announce_message), trust (create_trust_agent, TRUST_LEVELS, prompts) | unified networking API surface
+  Integration: exposes host(agent, port, trust), create_app(), IO/WebSocketIO, SessionStorage/Session, connect(url), RemoteAgent, Response, relay server (relay_connect, serve_loop), announce (create_announce_message), trust (TrustAgent) | unified networking API surface
   Performance: trivial
   Errors: none
 Network layer for hosting and connecting agents.
@@ -16,7 +16,7 @@ This module contains:
 - relay: Agent relay server for P2P discovery
 - connect: Multi-agent networking (RemoteAgent)
 - announce: Service announcement protocol
-- trust: Trust verification system
+- trust: Trust verification system (TrustAgent is the single interface)
 """
 
 from .host import host, create_app, SessionStorage, Session
@@ -24,7 +24,7 @@ from .io import IO, WebSocketIO
 from .connect import connect, RemoteAgent, Response
 from .relay import connect as relay_connect, serve_loop
 from .announce import create_announce_message
-from .trust import create_trust_agent, get_default_trust_level, TRUST_LEVELS, get_trust_prompt, TRUST_PROMPTS
+from .trust import TrustAgent, Decision, get_default_trust_level, TRUST_LEVELS, parse_policy
 from . import relay, announce
 
 __all__ = [
@@ -40,11 +40,12 @@ __all__ = [
     "relay_connect",
     "serve_loop",
     "create_announce_message",
-    "create_trust_agent",
+    # Trust (TrustAgent is the single interface)
+    "TrustAgent",
+    "Decision",
     "get_default_trust_level",
     "TRUST_LEVELS",
-    "get_trust_prompt",
-    "TRUST_PROMPTS",
+    "parse_policy",
     "relay",
     "announce",
 ]

connectonion/network/asgi/__init__.py

@@ -23,6 +23,7 @@ def create_app(
     route_handlers: dict,
     storage,
     trust: str = "careful",
+    trust_config: dict | None = None,
     blacklist: list | None = None,
     whitelist: list | None = None,
 ):
@@ -32,6 +33,7 @@ def create_app(
         route_handlers: Dict of route handler functions
         storage: SessionStorage instance
         trust: Trust level (open/careful/strict)
+        trust_config: Parsed YAML config from trust policy (for /info onboard)
         blacklist: Blocked identities
         whitelist: Allowed identities
 
@@ -49,6 +51,7 @@ def create_app(
                 route_handlers=route_handlers,
                 storage=storage,
                 trust=trust,
+                trust_config=trust_config,
                 start_time=start_time,
                 blacklist=blacklist,
                 whitelist=whitelist,

connectonion/network/asgi/http.py

@@ -107,6 +107,7 @@ async def handle_http(
     route_handlers: dict,
     storage,
     trust: str,
+    trust_config: dict | None = None,
     start_time: float,
     blacklist: list | None = None,
     whitelist: list | None = None,
@@ -120,6 +121,7 @@ async def handle_http(
         route_handlers: Dict of route handler functions (input, session, sessions, health, info, auth)
         storage: SessionStorage instance
         trust: Trust level (open/careful/strict)
+        trust_config: Parsed YAML config from trust policy (for /info onboard)
         start_time: Server start time
         blacklist: Blocked identities
         whitelist: Allowed identities
@@ -133,26 +135,130 @@ async def handle_http(
         await send({"type": "http.response.body", "body": b""})
         return
 
-    # Admin endpoints require API key auth
+    # Admin endpoints
     if path.startswith("/admin"):
-        headers = dict(scope.get("headers", []))
-        auth = headers.get(b"authorization", b"").decode()
-        expected = os.environ.get("OPENONION_API_KEY", "")
-        if not expected or not auth.startswith("Bearer ") or not hmac.compare_digest(auth[7:], expected):
-            await send_json(send, {"error": "unauthorized"}, 401)
-            return
-
-        if method == "GET" and path == "/admin/logs":
-            result = route_handlers["admin_logs"]()
-            if "error" in result:
-                await send_json(send, result, 404)
+        # Legacy admin endpoints (Bearer token auth)
+        if path in ["/admin/logs", "/admin/sessions"]:
+            headers_dict = dict(scope.get("headers", []))
+            auth = headers_dict.get(b"authorization", b"").decode()
+            expected = os.environ.get("OPENONION_API_KEY", "")
+            if not expected or not auth.startswith("Bearer ") or not hmac.compare_digest(auth[7:], expected):
+                await send_json(send, {"error": "unauthorized"}, 401)
+                return
+
+            if method == "GET" and path == "/admin/logs":
+                result = route_handlers["admin_logs"]()
+                if "error" in result:
+                    await send_json(send, result, 404)
+                else:
+                    await send_text(send, result["content"])
+                return
+
+            if method == "GET" and path == "/admin/sessions":
+                await send_json(send, route_handlers["admin_sessions"]())
+                return
+
+        # Admin trust routes (signed request + admin check)
+        if path.startswith("/admin/trust/") or path.startswith("/superadmin/"):
+            trust_agent = route_handlers["trust_agent"]
+
+            # For GET requests, allow auth via headers (bodies often stripped by proxies)
+            headers_dict = dict(scope.get("headers", []))
+            header_from = headers_dict.get(b"x-from", b"").decode()
+            header_sig = headers_dict.get(b"x-signature", b"").decode()
+            header_ts = headers_dict.get(b"x-timestamp", b"").decode()
+
+            if method == "GET" and header_from and header_sig and header_ts:
+                # Build signed request from headers
+                try:
+                    data = {
+                        "payload": {"timestamp": float(header_ts)},
+                        "from": header_from,
+                        "signature": header_sig
+                    }
+                except ValueError:
+                    await send_json(send, {"error": "Invalid X-Timestamp header"}, 400)
+                    return
             else:
-                await send_text(send, result["content"])
-            return
-
-        if method == "GET" and path == "/admin/sessions":
-            await send_json(send, route_handlers["admin_sessions"]())
-            return
+                # Read from body (POST or GET without headers)
+                body = await read_body(receive)
+                try:
+                    data = json.loads(body) if body else {}
+                except json.JSONDecodeError:
+                    await send_json(send, {"error": "Invalid JSON"}, 400)
+                    return
+
+            # Authenticate signed request (reuse same auth as /input, but with "open" trust)
+            _, identity, sig_valid, err = route_handlers["auth"](data, "open")
+            if err or not sig_valid:
+                await send_json(send, {"error": err or "unauthorized: invalid signature"}, 401)
+                return
+
+            # Check admin permission
+            if path.startswith("/superadmin/"):
+                # Super admin only (self address)
+                if not trust_agent.is_super_admin(identity):
+                    await send_json(send, {"error": "forbidden: super admin only"}, 403)
+                    return
+            else:
+                # Any admin
+                if not trust_agent.is_admin(identity):
+                    await send_json(send, {"error": "forbidden: admin only"}, 403)
+                    return
+
+            payload = data.get("payload", {})
+            client_id = payload.get("client_id")
+
+            # Route to handlers
+            if method == "POST" and path == "/admin/trust/promote":
+                if not client_id:
+                    await send_json(send, {"error": "client_id required"}, 400)
+                    return
+                await send_json(send, route_handlers["admin_trust_promote"](client_id))
+                return
+
+            if method == "POST" and path == "/admin/trust/demote":
+                if not client_id:
+                    await send_json(send, {"error": "client_id required"}, 400)
+                    return
+                await send_json(send, route_handlers["admin_trust_demote"](client_id))
+                return
+
+            if method == "POST" and path == "/admin/trust/block":
+                if not client_id:
+                    await send_json(send, {"error": "client_id required"}, 400)
+                    return
+                reason = payload.get("reason", "")
+                await send_json(send, route_handlers["admin_trust_block"](client_id, reason))
+                return
+
+            if method == "POST" and path == "/admin/trust/unblock":
+                if not client_id:
+                    await send_json(send, {"error": "client_id required"}, 400)
+                    return
+                await send_json(send, route_handlers["admin_trust_unblock"](client_id))
+                return
+
+            if method == "GET" and path.startswith("/admin/trust/level/"):
+                client_id = path[len("/admin/trust/level/"):]
+                await send_json(send, route_handlers["admin_trust_level"](client_id))
+                return
+
+            if method == "POST" and path == "/superadmin/add":
+                admin_id = payload.get("admin_id")
+                if not admin_id:
+                    await send_json(send, {"error": "admin_id required"}, 400)
+                    return
+                await send_json(send, route_handlers["admin_admins_add"](admin_id))
+                return
+
+            if method == "POST" and path == "/superadmin/remove":
+                admin_id = payload.get("admin_id")
+                if not admin_id:
+                    await send_json(send, {"error": "admin_id required"}, 400)
+                    return
+                await send_json(send, route_handlers["admin_admins_remove"](admin_id))
+                return
 
         await send_json(send, {"error": "not found"}, 404)
         return
@@ -189,7 +295,7 @@ async def handle_http(
         await send_json(send, route_handlers["health"](start_time))
 
     elif method == "GET" and path == "/info":
-        await send_json(send, route_handlers["info"](trust))
+        await send_json(send, route_handlers["info"](trust, trust_config))
 
     elif method == "GET" and path == "/docs":
         # Serve static docs page