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

connectonion/network/trust/trust_agent.py

@@ -0,0 +1,403 @@
+"""
+TrustAgent - A clear, method-based interface for trust management.
+
+Usage:
+    from connectonion.network.trust import TrustAgent
+
+    trust = TrustAgent("careful")  # or "open", "strict", or path to policy file
+
+    # Check if request is allowed
+    decision = trust.should_allow("client-123", {"prompt": "hello"})
+    if decision.allow:
+        # process request
+    else:
+        print(decision.reason)
+
+    # Trust level operations
+    trust.promote_to_contact("client-123")
+    trust.block("bad-actor", reason="spam")
+    level = trust.get_level("client-123")  # "stranger", "contact", "whitelist", "blocked"
+
+    # Admin operations
+    trust.is_admin("client-123")
+    trust.add_admin("new-admin")
+
+Extensibility:
+    Subclass TrustAgent to customize behavior. All methods can be overridden.
+
+    class MyTrustAgent(TrustAgent):
+        '''Custom trust with database-backed storage.'''
+
+        def is_admin(self, client_id: str) -> bool:
+            '''Check admin from database instead of file.'''
+            return self.db.is_admin(client_id)
+
+        def promote_to_contact(self, client_id: str) -> str:
+            '''Store contacts in database.'''
+            self.db.add_contact(client_id)
+            return f"{client_id} promoted to contact."
+
+    # Use custom trust agent
+    host(create_agent, trust=MyTrustAgent("careful"))
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .fast_rules import parse_policy, evaluate_request
+from .tools import (
+    is_whitelisted as _is_whitelisted,
+    is_blocked as _is_blocked,
+    is_contact as _is_contact,
+    is_stranger as _is_stranger,
+    promote_to_contact as _promote_to_contact,
+    promote_to_whitelist as _promote_to_whitelist,
+    demote_to_contact as _demote_to_contact,
+    demote_to_stranger as _demote_to_stranger,
+    block as _block,
+    unblock as _unblock,
+    get_level as _get_level,
+    # Admin functions
+    is_admin as _is_admin,
+    is_super_admin as _is_super_admin,
+    get_self_address as _get_self_address,
+    add_admin as _add_admin,
+    remove_admin as _remove_admin,
+)
+from .factory import PROMPTS_DIR, TRUST_LEVELS
+
+
+@dataclass
+class Decision:
+    """Result of should_allow() check."""
+    allow: bool
+    reason: str
+    used_llm: bool = False
+
+
+class TrustAgent:
+    """
+    Trust management with a clear, method-based interface.
+
+    All trust operations in one place:
+    - should_allow() - Check if request is allowed (fast rules + LLM fallback)
+    - verify_invite() / verify_payment() - Onboarding
+    - promote_to_contact() / promote_to_whitelist() - Promotion
+    - demote_to_contact() / demote_to_stranger() - Demotion
+    - block() / unblock() - Blocking
+    - get_level() - Query current level
+    - is_admin() / is_super_admin() - Admin checks
+    - add_admin() / remove_admin() - Admin management
+
+    Extensibility:
+        All methods can be overridden in subclasses for custom storage,
+        authentication backends, or business logic. See module docstring.
+    """
+
+    def __init__(self, trust: str = "careful", *, api_key: str = None, model: str = "co/gpt-4o-mini"):
+        """
+        Create a TrustAgent.
+
+        Args:
+            trust: Trust level ("open", "careful", "strict") or path to policy file
+            api_key: Optional API key for LLM (only needed if using 'ask' default)
+            model: Model to use for LLM decisions
+        """
+        self.trust = trust
+        self.api_key = api_key
+        self.model = model
+
+        # Load policy and parse config
+        self._config, self._prompt = self._load_policy(trust)
+
+        # Lazy-loaded LLM agent (only created if needed)
+        self._llm_agent = None
+
+    def _load_policy(self, trust: str) -> tuple[dict, str]:
+        """Load policy file and parse YAML config."""
+        # Trust level -> load from prompts/trust/{level}.md
+        if trust.lower() in TRUST_LEVELS:
+            policy_path = PROMPTS_DIR / f"{trust.lower()}.md"
+            if policy_path.exists():
+                text = policy_path.read_text(encoding='utf-8')
+                return parse_policy(text)
+            return {}, ""
+
+        # File path
+        path = Path(trust)
+        if path.exists() and path.is_file():
+            text = path.read_text(encoding='utf-8')
+            return parse_policy(text)
+
+        # Inline policy text
+        if trust.startswith('---'):
+            return parse_policy(trust)
+
+        # Unknown - empty config
+        return {}, ""
+
+    # === Main Decision Method ===
+
+    def should_allow(self, client_id: str, request: dict = None) -> Decision:
+        """
+        Check if a request should be allowed.
+
+        Runs fast rules first (no LLM). Only uses LLM if config has 'default: ask'.
+
+        Args:
+            client_id: The client making the request
+            request: Optional request data (may contain invite_code, payment)
+
+        Returns:
+            Decision with allow (bool) and reason (str)
+        """
+        request = request or {}
+
+        # Fast rules (no LLM)
+        result = evaluate_request(self._config, client_id, request)
+
+        if result == 'allow':
+            return Decision(allow=True, reason="Allowed by fast rules")
+        elif result == 'deny':
+            return Decision(allow=False, reason="Denied by fast rules")
+
+        # result is None -> need LLM decision
+        return self._llm_decide(client_id, request)
+
+    def _llm_decide(self, client_id: str, request: dict) -> Decision:
+        """Use LLM to make trust decision (only for 'ask' cases)."""
+        from ...core.agent import Agent
+        from ...llm_do import llm_do
+        from pydantic import BaseModel
+
+        class TrustDecision(BaseModel):
+            allow: bool
+            reason: str
+
+        # Build context for LLM
+        level = self.get_level(client_id)
+        prompt = f"""Evaluate this trust request:
+- client_id: {client_id}
+- current_level: {level}
+- request: {request}
+
+Should this client be allowed access?"""
+
+        decision = llm_do(
+            prompt,
+            output=TrustDecision,
+            system_prompt=self._prompt or "You are a trust evaluation agent. Decide if the request should be allowed.",
+            api_key=self.api_key,
+            model=self.model,
+        )
+
+        return Decision(allow=decision.allow, reason=decision.reason, used_llm=True)
+
+    # === Verification (Onboarding) ===
+
+    def verify_invite(self, client_id: str, invite_code: str) -> bool:
+        """
+        Verify invite code. Promotes to contact if valid.
+
+        Args:
+            client_id: Client to verify
+            invite_code: The invite code provided
+
+        Returns:
+            True if valid and promoted, False otherwise
+        """
+        valid_codes = self._config.get('onboard', {}).get('invite_code', [])
+        if invite_code in valid_codes:
+            self.promote_to_contact(client_id)
+            return True
+        return False
+
+    def verify_payment(self, client_id: str, amount: float) -> bool:
+        """
+        Verify payment via oo-api transfer verification.
+
+        Calls the oo-api to check if client_id transferred at least `amount`
+        to this agent's address within the last 5 minutes.
+
+        Args:
+            client_id: Client to verify (their address)
+            amount: Minimum payment amount required
+
+        Returns:
+            True if transfer verified and promoted, False otherwise
+        """
+        required = self._config.get('onboard', {}).get('payment')
+        if not required:
+            return False
+
+        # Use configured amount if not specified
+        min_amount = amount if amount > 0 else required
+
+        # Get self address (agent's address)
+        self_addr = self.get_self_address()
+        if not self_addr:
+            return False
+
+        # Call oo-api to verify transfer
+        if self._verify_transfer_via_api(client_id, self_addr, min_amount):
+            self.promote_to_contact(client_id)
+            return True
+        return False
+
+    def _verify_transfer_via_api(self, from_addr: str, to_addr: str, min_amount: float) -> bool:
+        """Call oo-api to verify a transfer was made."""
+        import os
+        import json
+        import time
+        from pathlib import Path
+
+        try:
+            import httpx
+        except ImportError:
+            # httpx not available, fall back to simple amount check
+            return True
+
+        # Load agent's keys for signing the request
+        from ... import address as addr
+
+        co_dir = Path.cwd() / '.co'
+        keys = addr.load(co_dir)
+        if not keys:
+            return False
+
+        # Determine API URL
+        base_url = os.environ.get('OPENONION_BASE_URL', 'https://oo.openonion.ai')
+        if os.environ.get('OPENONION_DEV'):
+            base_url = 'http://localhost:8000'
+
+        # Create signed auth request
+        timestamp = int(time.time())
+        message = f"ConnectOnion-Auth-{keys['public_key']}-{timestamp}"
+        signature = addr.sign(keys, message.encode()).hex()
+
+        # Get JWT token
+        auth_response = httpx.post(
+            f"{base_url}/auth",
+            json={
+                "public_key": keys['public_key'],
+                "message": message,
+                "signature": signature
+            },
+            timeout=10
+        )
+        if auth_response.status_code != 200:
+            return False
+
+        token = auth_response.json().get('token')
+        if not token:
+            return False
+
+        # Call verify endpoint
+        verify_response = httpx.post(
+            f"{base_url}/api/v1/onboard/verify",
+            json={
+                "from_address": from_addr,
+                "min_amount": min_amount
+            },
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10
+        )
+
+        if verify_response.status_code == 200:
+            result = verify_response.json()
+            return result.get('verified', False)
+
+        return False
+
+    # === Promotion ===
+
+    def promote_to_contact(self, client_id: str) -> str:
+        """Stranger -> Contact"""
+        return _promote_to_contact(client_id)
+
+    def promote_to_whitelist(self, client_id: str) -> str:
+        """Contact -> Whitelist"""
+        return _promote_to_whitelist(client_id)
+
+    # === Demotion ===
+
+    def demote_to_contact(self, client_id: str) -> str:
+        """Whitelist -> Contact"""
+        return _demote_to_contact(client_id)
+
+    def demote_to_stranger(self, client_id: str) -> str:
+        """Contact -> Stranger"""
+        return _demote_to_stranger(client_id)
+
+    # === Blocking ===
+
+    def block(self, client_id: str, reason: str = "") -> str:
+        """Add to blocklist."""
+        return _block(client_id, reason)
+
+    def unblock(self, client_id: str) -> str:
+        """Remove from blocklist."""
+        return _unblock(client_id)
+
+    # === Queries ===
+
+    def get_level(self, client_id: str) -> str:
+        """
+        Get client's current trust level.
+
+        Returns: "stranger", "contact", "whitelist", or "blocked"
+        """
+        return _get_level(client_id)
+
+    def is_whitelisted(self, client_id: str) -> bool:
+        """Check if client is whitelisted."""
+        return _is_whitelisted(client_id)
+
+    def is_blocked(self, client_id: str) -> bool:
+        """Check if client is blocked."""
+        return _is_blocked(client_id)
+
+    def is_contact(self, client_id: str) -> bool:
+        """Check if client is a contact."""
+        return _is_contact(client_id)
+
+    def is_stranger(self, client_id: str) -> bool:
+        """Check if client is a stranger."""
+        return _is_stranger(client_id)
+
+    # === Admin Management ===
+    # Instance methods for easy subclass overloading.
+    # Override these to customize admin logic (e.g., database-backed, LDAP, etc.)
+
+    def is_admin(self, client_id: str) -> bool:
+        """Check if client is an admin. Override for custom admin logic."""
+        return _is_admin(client_id)
+
+    def is_super_admin(self, client_id: str) -> bool:
+        """Check if client is super admin (self address). Override for custom logic."""
+        return _is_super_admin(client_id)
+
+    def get_self_address(self) -> str | None:
+        """Get self address (super admin)."""
+        return _get_self_address()
+
+    def add_admin(self, admin_id: str) -> str:
+        """Add an admin. Super admin only. Override for custom storage."""
+        return _add_admin(admin_id)
+
+    def remove_admin(self, admin_id: str) -> str:
+        """Remove an admin. Super admin only. Override for custom storage."""
+        return _remove_admin(admin_id)
+
+    # === Config Access ===
+
+    @property
+    def config(self) -> dict:
+        """Get the parsed YAML config."""
+        return self._config
+
+    @property
+    def prompt(self) -> str:
+        """Get the markdown prompt (for LLM decisions)."""
+        return self._prompt

connectonion/transcribe.py

@@ -70,7 +70,7 @@ def _get_api_key(model: str) -> str:
         api_key = os.getenv("OPENONION_API_KEY")
         if not api_key:
             # Try loading from config file
-            config_path = Path.home() / ".connectonion" / ".co" / "config.toml"
+            config_path = Path.home() / ".co" / "config.toml"
             if config_path.exists():
                 import toml
                 config = toml.load(config_path)

connectonion/useful_plugins/__init__.py

@@ -18,5 +18,6 @@ from .gmail_plugin import gmail_plugin
 from .calendar_plugin import calendar_plugin
 from .ui_stream import ui_stream
 from .system_reminder import system_reminder
+from .tool_approval import tool_approval
 
-__all__ = ['re_act', 'eval', 'image_result_formatter', 'shell_approval', 'gmail_plugin', 'calendar_plugin', 'ui_stream', 'system_reminder']
+__all__ = ['re_act', 'eval', 'image_result_formatter', 'shell_approval', 'gmail_plugin', 'calendar_plugin', 'ui_stream', 'system_reminder', 'tool_approval']

connectonion/useful_plugins/tool_approval.py

@@ -0,0 +1,233 @@
+"""
+Purpose: Web-based tool approval plugin - request user approval before dangerous tools
+LLM-Note:
+  Dependencies: imports from [core/events.py] | imported by [useful_plugins/__init__.py] | tested by [tests/unit/test_tool_approval.py]
+  Data flow: before_each_tool fires → check if dangerous tool → io.send(approval_needed) → io.receive() blocks → approved: continue, rejected: raise ValueError
+  State/Effects: stores approved_tools in session for "session" scope approvals | blocks on io.receive() until client responds | logs all approval decisions via agent.logger
+  Integration: exposes tool_approval plugin list | uses agent.io for WebSocket communication | requires client to handle "approval_needed" events
+  Errors: raises ValueError on rejection (stops batch, feedback sent to LLM)
+
+Tool Approval Plugin - Request client approval before executing dangerous tools.
+
+WebSocket-only. Uses io.send/receive pattern:
+1. Sends {type: "approval_needed", tool, arguments} to client
+2. Blocks until client responds with {approved: bool, scope?, feedback?}
+3. If approved: execute tool (optionally save to session memory)
+4. If rejected: raise ValueError, stopping batch, LLM sees feedback
+
+Tool Classification:
+- SAFE_TOOLS: Read-only operations (read, glob, grep, etc.) - never need approval
+- DANGEROUS_TOOLS: Write/execute operations (bash, write, edit, etc.) - always need approval
+- Unknown tools: Treated as safe (no approval needed)
+
+Session Memory:
+- scope="once": Approve for this call only
+- scope="session": Approve for rest of session (no re-prompting)
+
+Rejection Behavior:
+- Raises ValueError with user feedback
+- Stops entire tool batch (remaining tools skipped)
+- LLM receives error message and can adjust approach
+
+Usage:
+    from connectonion import Agent
+    from connectonion.useful_plugins import tool_approval
+
+    agent = Agent("assistant", tools=[bash, write], plugins=[tool_approval])
+
+Client Protocol:
+    # Receive from server:
+    {"type": "approval_needed", "tool": "bash", "arguments": {"command": "npm install"}}
+
+    # Send response:
+    {"approved": true, "scope": "session"}  # Approve for session
+    {"approved": true, "scope": "once"}     # Approve once
+    {"approved": false, "feedback": "Use yarn instead"}  # Reject with feedback
+"""
+
+from typing import TYPE_CHECKING
+
+from ..core.events import before_each_tool
+
+if TYPE_CHECKING:
+    from ..core.agent import Agent
+
+
+# Tools that NEVER need approval (read-only, safe)
+# These tools cannot modify system state or have external side effects.
+# Add new read-only tools here to skip approval prompts.
+SAFE_TOOLS = {
+    # File reading - read contents without modification
+    'read', 'read_file',
+    # Search operations - find files/content without modification
+    'glob', 'grep', 'search',
+    # Info operations - query metadata only
+    'list_files', 'get_file_info',
+    # Agent operations - sub-agents handle their own approval
+    'task',
+    # Documentation - load reference materials
+    'load_guide',
+    # Planning - state management without side effects
+    'enter_plan_mode', 'exit_plan_mode', 'write_plan',
+    # Task management - read-only task status
+    'task_output',
+    # User interaction - prompts user, not system modification
+    'ask_user',
+}
+
+# Tools that ALWAYS need approval (destructive/side-effects)
+# These tools can modify files, execute code, or have external effects.
+# User approval required before execution in web mode.
+DANGEROUS_TOOLS = {
+    # Shell execution - arbitrary command execution
+    'bash', 'shell', 'run', 'run_in_dir',
+    # File modification - write/edit file contents
+    'write', 'edit', 'multi_edit',
+    # Background tasks - long-running command execution
+    'run_background',
+    # Task control - terminate running processes
+    'kill_task',
+    # External communication - send data outside system
+    'send_email', 'post',
+    # Deletion - remove files/resources
+    'delete', 'remove',
+}
+
+
+# Session state helpers for approval memory
+# These functions manage the session['approval'] dict which tracks
+# which tools have been approved for the current session.
+
+def _init_approval_state(session: dict) -> None:
+    """Initialize approval state in session if not present.
+
+    Creates session['approval']['approved_tools'] dict for storing
+    tool approvals with scope='session'.
+    """
+    if 'approval' not in session:
+        session['approval'] = {
+            'approved_tools': {},  # tool_name -> 'session'
+        }
+
+
+def _is_approved_for_session(session: dict, tool_name: str) -> bool:
+    """Check if tool was approved for this session.
+
+    Returns True if user previously approved this tool with scope='session'.
+    """
+    approval = session.get('approval', {})
+    return approval.get('approved_tools', {}).get(tool_name) == 'session'
+
+
+def _save_session_approval(session: dict, tool_name: str) -> None:
+    """Save tool as approved for this session.
+
+    Future calls to the same tool will skip approval prompts.
+    """
+    _init_approval_state(session)
+    session['approval']['approved_tools'][tool_name] = 'session'
+
+
+def _log(agent: 'Agent', message: str, style: str = None) -> None:
+    """Log message via agent's logger if available.
+
+    Args:
+        agent: Agent instance
+        message: Message to log
+        style: Rich style string (e.g., "[green]", "[red]")
+    """
+    if hasattr(agent, 'logger') and agent.logger:
+        agent.logger.print(message, style)
+
+
+@before_each_tool
+def check_approval(agent: 'Agent') -> None:
+    """Check if tool needs approval and request from client.
+
+    Flow:
+    1. Skip if no IO (not web mode)
+    2. Skip if safe tool
+    3. Skip if unknown tool (default: safe)
+    4. Skip if already approved for session
+    5. Send approval_needed, wait for response
+    6. If approved: optionally save to session, continue
+    7. If rejected: raise ValueError (stops batch)
+
+    Logging:
+    - Logs approval requests, approvals, and rejections
+    - Uses agent.logger.print() for terminal output
+
+    Raises:
+        ValueError: If user rejects the tool (includes feedback if provided)
+    """
+    # No IO = not web mode, skip
+    if not agent.io:
+        return
+
+    # Get pending tool info
+    pending = agent.current_session.get('pending_tool')
+    if not pending:
+        return
+
+    tool_name = pending['name']
+    tool_args = pending['arguments']
+
+    # Safe tools don't need approval
+    if tool_name in SAFE_TOOLS:
+        return
+
+    # Unknown tools (not in SAFE or DANGEROUS) are treated as safe
+    if tool_name not in DANGEROUS_TOOLS:
+        return
+
+    # Already approved for this session
+    if _is_approved_for_session(agent.current_session, tool_name):
+        _log(agent, f"[dim]⏭ {tool_name} (session-approved)[/dim]")
+        return
+
+    # Send approval request to client
+    agent.io.send({
+        'type': 'approval_needed',
+        'tool': tool_name,
+        'arguments': tool_args,
+    })
+
+    # Wait for client response (BLOCKS)
+    response = agent.io.receive()
+
+    # Handle connection closed
+    if response.get('type') == 'io_closed':
+        _log(agent, f"[red]✗ {tool_name} - connection closed[/red]")
+        raise ValueError(f"Connection closed while waiting for approval of '{tool_name}'")
+
+    # Check approval
+    approved = response.get('approved', False)
+
+    if approved:
+        # Save to session if scope is "session"
+        scope = response.get('scope', 'once')
+        if scope == 'session':
+            _save_session_approval(agent.current_session, tool_name)
+            _log(agent, f"[green]✓ {tool_name} approved (session)[/green]")
+        else:
+            _log(agent, f"[green]✓ {tool_name} approved (once)[/green]")
+        # Continue to execute tool
+        return
+
+    # Rejected - raise ValueError to stop batch
+    feedback = response.get('feedback', '')
+    if feedback:
+        _log(agent, f"[red]✗ {tool_name} rejected: {feedback}[/red]")
+    else:
+        _log(agent, f"[red]✗ {tool_name} rejected[/red]")
+
+    error_msg = f"User rejected tool '{tool_name}'."
+    if feedback:
+        error_msg += f" Feedback: {feedback}"
+    raise ValueError(error_msg)
+
+
+# Export as plugin (list of event handlers)
+# Usage: Agent("name", plugins=[tool_approval])
+# The plugin registers check_approval as a before_each_tool handler
+tool_approval = [check_approval]

{connectonion-0.6.3.dist-info → connectonion-0.6.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: connectonion
-Version: 0.6.3
+Version: 0.6.5
 Summary: A simple Python framework for creating AI agents with behavior tracking
 Project-URL: Homepage, https://github.com/openonion/connectonion
 Project-URL: Documentation, https://docs.connectonion.com