connectonion 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

connectonion/network/host/session.py

@@ -0,0 +1,78 @@
+"""
+Purpose: Persistent session storage for hosted agent requests with TTL expiry
+LLM-Note:
+  Dependencies: imports from [pydantic.BaseModel, pathlib, json, time] | imported by [network/host/routes.py, network/host/server.py] | tested by [tests/network/test_session_storage.py]
+  Data flow: save(session) appends Session to JSONL file (.co/session_results.jsonl) → get(session_id) reads file backwards → returns latest matching session if not expired → list() loads all sessions → filters expired ones → sorts by created desc
+  State/Effects: writes to .co/session_results.jsonl (append-only) | creates .co/ directory | auto-expires sessions based on expires timestamp | last entry wins (duplicates overridden by latest)
+  Integration: exposes Session(session_id, status, prompt, result, created, expires, duration_ms) Pydantic model | SessionStorage(path) with .save(session), .get(session_id) → Session|None, .list() → list[Session] | used by routes to persist and retrieve agent execution results
+  Performance: append-only writes (fast) | linear scan on read (acceptable for thousands of sessions) | file-based (simple, no DB required) | TTL filtering prevents unbounded growth
+  Errors: returns None if session not found or expired | creates parent directory if missing | no exceptions raised
+Session storage for hosted agents.
+"""
+
+import json
+import time
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class Session(BaseModel):
+    """Session record for tracking agent requests.
+
+    Uses Pydantic BaseModel for:
+    - Native JSON serialization via .model_dump()
+    - Type validation
+    - API response compatibility
+    """
+    session_id: str
+    status: str
+    prompt: str
+    result: Optional[str] = None
+    created: Optional[float] = None
+    expires: Optional[float] = None
+    duration_ms: Optional[int] = None
+
+
+class SessionStorage:
+    """JSONL file storage. Append-only, last entry wins."""
+
+    def __init__(self, path: str = ".co/session_results.jsonl"):
+        self.path = Path(path)
+        self.path.parent.mkdir(exist_ok=True)
+
+    def save(self, session: Session):
+        with open(self.path, "a") as f:
+            f.write(session.model_dump_json() + "\n")
+
+    def get(self, session_id: str) -> Session | None:
+        if not self.path.exists():
+            return None
+        now = time.time()
+        with open(self.path) as f:
+            lines = f.readlines()
+        for line in reversed(lines):
+            data = json.loads(line)
+            if data["session_id"] == session_id:
+                session = Session(**data)
+                # Return if running or not expired
+                if session.status == "running" or not session.expires or session.expires > now:
+                    return session
+                return None  # Expired
+        return None
+
+    def list(self) -> list[Session]:
+        if not self.path.exists():
+            return []
+        sessions = {}
+        now = time.time()
+        with open(self.path) as f:
+            for line in f:
+                data = json.loads(line)
+                sessions[data["session_id"]] = Session(**data)
+        # Filter out expired non-running sessions
+        valid = [s for s in sessions.values()
+                 if s.status == "running" or not s.expires or s.expires > now]
+        # Sort by created desc (newest first)
+        return sorted(valid, key=lambda s: s.created or 0, reverse=True)

connectonion/network/io/__init__.py

@@ -0,0 +1,21 @@
+"""
+Purpose: IO module re-exporting base IO protocol and WebSocket implementation
+LLM-Note:
+  Dependencies: imports from [base.py, websocket.py] | imported by [network/__init__.py, agent.py, network/asgi/websocket.py] | tested by [tests/network/test_io.py]
+  Data flow: re-exports IO abstract class and WebSocketIO concrete implementation
+  State/Effects: no state
+  Integration: exposes IO(ABC) protocol with send(event), receive() → dict, log(type, **data), request_approval(tool, args) → bool | WebSocketIO uses queue-based async-to-sync bridge for agent.io attribute
+  Performance: trivial
+  Errors: none
+IO module for agent-client communication.
+
+Provides the IO interface and WebSocket implementation.
+"""
+
+from .base import IO
+from .websocket import WebSocketIO
+
+__all__ = [
+    "IO",
+    "WebSocketIO",
+]

connectonion/network/{connection.py → io/base.py}

@@ -1,20 +1,21 @@
 """
-Purpose: Connection interface for agent-client communication during hosted execution
+Purpose: Abstract IO interface for bidirectional agent-client communication in hosted agents
 LLM-Note:
-  Dependencies: imports from [abc, typing] | imported by [asgi.py, __init__.py] | tested by [tests/unit/test_connection.py]
-  Data flow: receives from host/asgi → WebSocket send/receive → provides log() and request_approval() to agent event handlers
-  State/Effects: stateless base class | WebSocketConnection wraps ASGI WebSocket for bidirectional messaging
-  Integration: exposes Connection (base), WebSocketConnection (ASGI adapter) | agent.connection set by host() during WebSocket requests
-  Performance: log() is fire-and-forget (non-blocking) | request_approval() blocks waiting for client response
-  Errors: WebSocketConnection raises if WebSocket closed unexpectedly
+  Dependencies: imports from [abc.ABC, typing] | imported by [network/io/websocket.py, network/__init__.py, agent.py] | tested by [tests/network/test_io.py]
+  Data flow: agent.io.send(event) → client receives event → agent.io.receive() → blocks until client responds | high-level: io.log(type, **data) for one-way notifications | io.request_approval(tool, args) sends approval_needed → waits for client response → returns True/False
+  State/Effects: no state (abstract base class) | implementations handle message queuing/transport
+  Integration: exposes IO abstract class with send(event), receive() → dict primitives | convenience methods: log(type, **data), request_approval(tool, args) → bool | agent.io injected by host() for hosted execution | used in event handlers (@after_llm, @before_each_tool)
+  Performance: abstract (implementation-specific) | WebSocketIO uses queue.Queue for thread-safe communication
+  Errors: abstract methods must be implemented by subclasses | request_approval() blocks until response (timeout handled by implementation)
+IO interface for agent-client communication during hosted execution.
 """
 
 from abc import ABC, abstractmethod
 from typing import Any, Dict
 
 
-class Connection(ABC):
-    """Base connection interface for agent-client communication.
+class IO(ABC):
+    """Base IO interface for agent-client communication.
 
     Two-layer API:
     - Low-level: send(event), receive() - primitives for any communication
@@ -23,15 +24,15 @@ class Connection(ABC):
     Usage in event handlers:
         @after_llm
         def on_thinking(agent):
-            if agent.connection:
-                agent.connection.log("thinking")
+            if agent.io:
+                agent.io.log("thinking")
 
         @before_each_tool
         def on_tool(agent):
-            if agent.connection:
+            if agent.io:
                 tool = agent.current_session['pending_tool']
                 if tool['name'] in DANGEROUS:
-                    if not agent.connection.request_approval(tool['name'], tool['arguments']):
+                    if not agent.io.request_approval(tool['name'], tool['arguments']):
                         raise ToolRejected()
     """
 
@@ -71,8 +72,8 @@ class Connection(ABC):
             **data: Additional data for the event
 
         Example:
-            connection.log("thinking")
-            connection.log("tool_call", name="search", arguments={"q": "python"})
+            io.log("thinking")
+            io.log("tool_call", name="search", arguments={"q": "python"})
         """
         self.send({"type": event_type, **data})
 
@@ -89,35 +90,9 @@ class Connection(ABC):
             True if approved, False if rejected
 
         Example:
-            if not connection.request_approval("delete_file", {"path": "/tmp/x"}):
+            if not io.request_approval("delete_file", {"path": "/tmp/x"}):
                 raise ToolRejected()
         """
         self.send({"type": "approval_needed", "tool": tool, "arguments": arguments})
         response = self.receive()
         return response.get("approved", False)
-
-
-class SyncWebSocketConnection(Connection):
-    """Synchronous WebSocket connection adapter.
-
-    Wraps async WebSocket send/receive for use in synchronous agent code.
-    Uses threading events to bridge async/sync boundary.
-    """
-
-    def __init__(self, send_callback, receive_callback):
-        """Initialize with send/receive callbacks.
-
-        Args:
-            send_callback: Callable that sends message to WebSocket
-            receive_callback: Callable that receives message from WebSocket
-        """
-        self._send = send_callback
-        self._receive = receive_callback
-
-    def send(self, event: Dict[str, Any]) -> None:
-        """Send event to client via WebSocket."""
-        self._send(event)
-
-    def receive(self) -> Dict[str, Any]:
-        """Receive response from client via WebSocket."""
-        return self._receive()

connectonion/network/io/websocket.py

@@ -0,0 +1,55 @@
+"""
+Purpose: WebSocket IO implementation bridging async WebSocket to sync agent code via queues
+LLM-Note:
+  Dependencies: imports from [network/io/base.py IO, queue, time, uuid, typing] | imported by [network/asgi/websocket.py, network/host/server.py] | tested by [tests/network/test_websocket_io.py]
+  Data flow: agent calls io.send(event) → auto-adds id (UUID) and ts if missing → puts in _outgoing queue → async handler gets via queue.get() → sends via WebSocket | client sends message → async handler puts in _incoming queue → agent blocks on io.receive() → gets from _incoming | close() unblocks waiting receive() with io_closed event
+  State/Effects: maintains _outgoing and _incoming queues (thread-safe) | _closed flag prevents sending after close | receive() blocks until message available | auto-generates UUID for events without id (for frontend React keys)
+  Integration: exposes WebSocketIO() implementing IO interface | send(event) queues outgoing message with auto-id, receive() → dict blocks for incoming message, close() marks closed | used by handle_websocket() to provide agent.io for bidirectional communication
+  Performance: queue-based (thread-safe, no locks needed) | blocking receive() (use in agent thread) | async handler pumps messages between WebSocket and queues
+  Errors: closed IO puts io_closed sentinel in _incoming to unblock receive() | no exceptions (queue handles thread coordination)
+WebSocket IO implementation.
+"""
+
+import queue
+import time
+import uuid
+from typing import Any, Dict
+
+from .base import IO
+
+
+class WebSocketIO(IO):
+    """Bridge async WebSocket to sync IO interface.
+
+    Uses queues to communicate between async WebSocket handler and sync agent code.
+    The agent runs in a thread, sending/receiving via queues.
+    The async handler pumps messages between WebSocket and queues.
+    """
+
+    def __init__(self):
+        self._outgoing: queue.Queue[Dict[str, Any]] = queue.Queue()
+        self._incoming: queue.Queue[Dict[str, Any]] = queue.Queue()
+        self._closed = False
+
+    def send(self, event: Dict[str, Any]) -> None:
+        """Queue event to be sent to client.
+
+        Auto-generates 'id' (UUID) and 'ts' (timestamp) if not present,
+        ensuring all events have unique IDs for frontend React keys.
+        """
+        if not self._closed:
+            if 'id' not in event:
+                event['id'] = str(uuid.uuid4())
+            if 'ts' not in event:
+                event['ts'] = time.time()
+            self._outgoing.put(event)
+
+    def receive(self) -> Dict[str, Any]:
+        """Block until response from client."""
+        return self._incoming.get()
+
+    def close(self):
+        """Mark IO as closed."""
+        self._closed = True
+        # Unblock any waiting receive
+        self._incoming.put({"type": "io_closed"})

connectonion/network/relay.py

@@ -1,17 +1,35 @@
 """
-Purpose: WebSocket relay client for agent-to-agent communication via central relay server using INPUT/OUTPUT protocol
-LLM-Note:
-  Dependencies: imports from [json, asyncio, typing, websockets] | imported by [host.py] | tested by [tests/test_relay.py]
-  Data flow: host() with relay_url → connect(relay_url) → WebSocket established → send_announce(ws, announce_msg) → serve_loop() → wait_for_task(ws) receives INPUT message from relay → task_handler(prompt) executes → send OUTPUT response via WebSocket → heartbeat re-announces every 60s
-  State/Effects: maintains WebSocket connection to relay | reads incoming JSON messages (INPUT type) | writes outgoing JSON messages (OUTPUT type) | prints status to stdout | asyncio timeout for heartbeat | no file I/O
-  Integration: exposes connect(relay_url), send_announce(ws, msg), wait_for_task(ws, timeout), send_response(ws, input_id, result), serve_loop(ws, announce_msg, task_handler, heartbeat_interval) | used by host() with relay_url to make agent discoverable on relay network | task_handler is async function (prompt: str) -> str | Protocol: INPUT/OUTPUT messages (not TASK/RESPONSE)
-  Performance: async/await non-blocking I/O | heartbeat_interval=60s default (configurable) | timeout-based heartbeat scheduling | WebSocket maintains persistent connection
-  Errors: let it crash - ImportError if websockets missing | asyncio.TimeoutError used for heartbeat timing | websockets.ConnectionClosed exits serve loop gracefully
-
-WebSocket relay client functions.
+Purpose: Agent-side relay client for registering and serving via central relay server
+
+Lifecycle (Agent Side):
+  1. connect(relay_url) opens WebSocket to /ws/announce
+  2. send_announce() sends ANNOUNCE message to register agent
+  3. serve_loop() waits for INPUT messages from relay
+  4. On INPUT: task_handler(prompt) processes → sends OUTPUT back
+  5. Heartbeat: re-sends ANNOUNCE every 60s to stay registered
+
+Message Flow:
+  Agent → ANNOUNCE → Relay (registers in active_connections)
+  Client → INPUT → Relay → forwards to Agent's WebSocket
+  Agent → OUTPUT → Relay → forwards to Client's /ws/input connection
+
+Protocol:
+  ANNOUNCE: {type, address, summary, endpoints, signature, timestamp}
+  INPUT:    {type, input_id, prompt, from_address?, session?}
+  OUTPUT:   {type, input_id, result, session?}
+  TODO: Adopt WebRTC-style ICE candidates (host/srflx/relay) and connectivity
+        checks so clients can prefer direct endpoints when possible.
+
+Related Files:
+  - oo-api/relay/routes.py: Relay server that receives these messages
+  - connectonion/network/connect.py: Client-side (sends INPUT, receives OUTPUT)
+  - connectonion/network/host/server.py: Uses this for relay registration
 
-Simple async functions for connecting to relay and exchanging messages using INPUT/OUTPUT protocol.
-No classes needed - just stateless functions operating on websocket connections.
+LLM-Note:
+  Dependencies: imports from [json, asyncio, typing, websockets]
+  Data flow: connect() → /ws/announce → serve_loop() → INPUT → task_handler → OUTPUT
+  State/Effects: WebSocket connection to relay | heartbeat every 60s
+  Integration: exposes connect(), send_announce(), wait_for_task(), serve_loop()
 """
 
 import json
@@ -20,12 +38,12 @@ from typing import Dict, Any
 import websockets
 
 
-async def connect(relay_url: str = "wss://oo.openonion.ai/ws/announce"):
+async def connect(relay_url: str = "wss://oo.openonion.ai"):
     """
-    Connect to relay WebSocket endpoint.
+    Connect to relay's announce endpoint.
 
     Args:
-        relay_url: WebSocket URL for relay (default: production relay)
+        relay_url: Relay server base URL (default: production relay)
 
     Returns:
         WebSocket connection object
@@ -34,7 +52,10 @@ async def connect(relay_url: str = "wss://oo.openonion.ai/ws/announce"):
         >>> ws = await connect()
         >>> # Now use ws for sending/receiving
     """
-    return await websockets.connect(relay_url)
+    ws_url = f"{relay_url.rstrip('/')}/ws/announce"
+    # TODO: Future connection metadata (observed_ip, ICE candidates) should be
+    #       attached to ANNOUNCE so relay can return best endpoints to clients.
+    return await websockets.connect(ws_url)
 
 
 async def send_announce(websocket, announce_message: Dict[str, Any]):

connectonion/network/trust/__init__.py

@@ -0,0 +1,30 @@
+"""
+Purpose: Trust verification system module re-exporting factory, prompts, and verification tools
+LLM-Note:
+  Dependencies: imports from [factory.py, prompts.py, tools.py] | imported by [network/__init__.py, network/host/auth.py, network/host/server.py] | tested by [tests/network/test_trust.py]
+  Data flow: re-exports trust agent creation utilities and trust level prompts
+  State/Effects: no state
+  Integration: exposes create_trust_agent(trust_spec) → Agent, get_default_trust_level() → str, validate_trust_level(level), TRUST_LEVELS dict, TRUST_PROMPTS dict, get_trust_prompt(level) → str, get_trust_verification_tools() → list | used by host() for access control policies
+  Performance: trivial
+  Errors: none
+Trust verification system for agent networking.
+
+This module contains:
+- factory: Trust agent creation and configuration
+- prompts: Pre-configured trust prompts for different levels
+- tools: Verification tools for trust agents
+"""
+
+from .factory import create_trust_agent, get_default_trust_level, validate_trust_level, TRUST_LEVELS
+from .prompts import TRUST_PROMPTS, get_trust_prompt
+from .tools import get_trust_verification_tools
+
+__all__ = [
+    "create_trust_agent",
+    "get_default_trust_level",
+    "validate_trust_level",
+    "TRUST_LEVELS",
+    "TRUST_PROMPTS",
+    "get_trust_prompt",
+    "get_trust_verification_tools",
+]

connectonion/network/trust/factory.py

@@ -0,0 +1,138 @@
+"""
+Purpose: Factory for creating trust verification agents with policies.
+
+String Resolution Priority:
+  1. Trust level ("open", "careful", "strict")
+  2. File path (if exists)
+  3. Inline policy text
+
+LLM-Note:
+  Dependencies: [os, pathlib, typing, .prompts, .tools] | imported by [host/server.py] | tested by [tests/unit/test_trust.py]
+  Data flow: trust param → check env default → resolve by priority → return Agent or None
+  Errors: TypeError (invalid type) | FileNotFoundError (Path doesn't exist)
+"""
+
+import os
+from pathlib import Path
+from typing import Union, Optional
+
+from .prompts import get_trust_prompt
+from .tools import get_trust_verification_tools
+
+
+# Trust level constants
+TRUST_LEVELS = ["open", "careful", "strict"]
+
+
+def get_default_trust_level() -> Optional[str]:
+    """
+    Get default trust level based on environment.
+    
+    Returns:
+        Default trust level or None
+    """
+    env = os.environ.get('CONNECTONION_ENV', '').lower()
+    
+    if env == 'development':
+        return 'open'
+    elif env == 'production':
+        return 'strict'
+    elif env in ['staging', 'test']:
+        return 'careful'
+    
+    return None
+
+
+def create_trust_agent(trust: Union[str, Path, 'Agent', None], api_key: Optional[str] = None, model: str = "gpt-5-mini") -> Optional['Agent']:
+    """
+    Create a trust agent based on the trust parameter.
+
+    Args:
+        trust: Trust configuration:
+            - None: Check CONNECTONION_TRUST env, else return None
+            - Agent: Return as-is (must have tools)
+            - Path: Read file as policy
+            - str: Resolved by priority:
+                1. Trust level ("open", "careful", "strict")
+                2. File path (if file exists)
+                3. Inline policy text
+
+    Returns:
+        Agent configured for trust verification, or None
+    """
+    from ...core.agent import Agent  # Import here to avoid circular dependency
+    
+    # If None, check for environment default
+    if trust is None:
+        env_trust = os.environ.get('CONNECTONION_TRUST')
+        if env_trust:
+            trust = env_trust
+        else:
+            return None  # No trust agent
+    
+    # If it's already an Agent, validate and return it
+    if isinstance(trust, Agent):
+        if not trust.tools:
+            raise ValueError("Trust agent must have verification tools")
+        return trust
+    
+    # Get trust verification tools
+    trust_tools = get_trust_verification_tools()
+    
+    # Handle Path object
+    if isinstance(trust, Path):
+        if not trust.exists():
+            raise FileNotFoundError(f"Trust policy file not found: {trust}")
+        policy = trust.read_text(encoding='utf-8')
+        return Agent(
+            name="trust_agent_custom",
+            tools=trust_tools,
+            system_prompt=policy,
+            api_key=api_key,
+            model=model
+        )
+    
+    # Handle string: trust level > file path > inline policy
+    if isinstance(trust, str):
+        if trust.lower() in TRUST_LEVELS:
+            return Agent(
+                name=f"trust_agent_{trust.lower()}",
+                tools=trust_tools,
+                system_prompt=get_trust_prompt(trust.lower()),
+                api_key=api_key,
+                model=model
+            )
+
+        path = Path(trust)
+        if path.exists() and path.is_file():
+            return Agent(
+                name="trust_agent_custom",
+                tools=trust_tools,
+                system_prompt=path.read_text(encoding='utf-8'),
+                api_key=api_key,
+                model=model
+            )
+
+        return Agent(
+            name="trust_agent_custom",
+            tools=trust_tools,
+            system_prompt=trust,
+            api_key=api_key,
+            model=model
+        )
+    
+    # Invalid type
+    raise TypeError(f"Trust must be a string (level/policy/path), Path, Agent, or None, not {type(trust).__name__}")
+
+
+def validate_trust_level(level: str) -> bool:
+    """
+    Check if a string is a valid trust level.
+    
+    Args:
+        level: String to check
+        
+    Returns:
+        True if valid trust level, False otherwise
+    """
+    return level.lower() in TRUST_LEVELS

connectonion/network/{trust_agents.py → trust/prompts.py}

@@ -1,10 +1,10 @@
 """
 Purpose: Provide pre-configured system prompts for trust agents at different security levels
 LLM-Note:
-  Dependencies: no imports | imported by [trust.py] | tested by [tests/test_trust.py]
-  Data flow: trust.py calls get_trust_prompt(level) → validates level → returns TRUST_PROMPTS[level] string → used as system_prompt for trust Agent
+  Dependencies: no imports | imported by [.factory] | tested by [tests/unit/test_trust_agents.py]
+  Data flow: factory.py calls get_trust_prompt(level) → validates level → returns TRUST_PROMPTS[level] string → used as system_prompt for trust Agent
   State/Effects: no state or side effects | pure data module | TRUST_PROMPTS dict contains 3 prompts: "open" (dev - trust all), "careful" (staging - basic verification), "strict" (prod - whitelist only)
-  Integration: exposes TRUST_PROMPTS dict, get_trust_prompt(level), get_open_trust_prompt(), get_careful_trust_prompt(), get_strict_trust_prompt() | used by create_trust_agent() in trust.py to configure trust agent behavior
+  Integration: exposes TRUST_PROMPTS dict, get_trust_prompt(level), get_open_trust_prompt(), get_careful_trust_prompt(), get_strict_trust_prompt() | used by create_trust_agent() in factory.py to configure trust agent behavior
   Performance: constant-time dict lookup | no computation
   Errors: raises ValueError if level not in ["open", "careful", "strict"]
 """

connectonion/network/{trust_functions.py → trust/tools.py}

@@ -1,10 +1,10 @@
 """
 Purpose: Provide tool functions for trust agents to verify other agents
 LLM-Note:
-  Dependencies: imports from [pathlib, typing] | imported by [trust.py] | tested by [tests/test_trust.py]
+  Dependencies: imports from [pathlib, typing] | imported by [.factory] | tested by [tests/unit/test_trust_functions.py]
   Data flow: create_trust_agent() calls get_trust_verification_tools() → returns list of [check_whitelist, test_capability, verify_agent] functions → these become tools for trust Agent → trust agent calls tools with agent_id → functions return descriptive strings → AI interprets results per trust policy
   State/Effects: check_whitelist() reads ~/.connectonion/trusted.txt file if exists | supports wildcard patterns with * | test_capability() and verify_agent() are pure (no I/O, just return descriptive strings for AI)
-  Integration: exposes check_whitelist(agent_id), test_capability(agent_id, test, expected), verify_agent(agent_id, agent_info), get_trust_verification_tools() | used by trust.py to equip trust agents with verification capabilities
+  Integration: exposes check_whitelist(agent_id), test_capability(agent_id, test, expected), verify_agent(agent_id, agent_info), get_trust_verification_tools() | used by factory.py to equip trust agents with verification capabilities
   Performance: file read only for check_whitelist | simple string operations | no network calls
   Errors: check_whitelist() catches file read exceptions and returns error string | missing whitelist file returns helpful message | no exceptions raised (errors returned as strings for AI interpretation)
 """

connectonion/prompt_files/__init__.py

@@ -1 +1,11 @@
-"""Prompts module for ConnectOnion built-in plugins."""
+"""
+Purpose: Prompt files namespace for built-in plugin markdown prompts (empty module)
+LLM-Note:
+  Dependencies: none | imported by [prompts.py via load_system_prompt] | contains markdown files (reflect.md, etc.)
+  Data flow: namespace only (contains .md files, no code)
+  State/Effects: no state
+  Integration: directory contains prompt files loaded by plugins (e.g., useful_events_handlers/reflect.py loads prompt_files/reflect.md)
+  Performance: trivial
+  Errors: none
+Prompts module for ConnectOnion built-in plugins.
+"""

connectonion/prompt_files/react_acknowledge.md

@@ -0,0 +1,26 @@
+# ReAct Acknowledge
+
+You acknowledge user requests and show you understand their real need from context.
+Be proactive - even brief inputs like "yes" or "fix it" have meaning in context.
+
+## Guidelines
+
+- Keep it SHORT: 1-2 sentences max
+- Start with "I" or "Got it"
+- Show you understood the CONTEXT, not just the literal words
+- For brief inputs, reference what you're acting on
+
+## Examples
+
+- User: "build a web scraper" → "Got it, I'll build a scraper that handles pagination and extracts the data cleanly."
+- User: "yes" → "Got it, I'll proceed with the approach we discussed."
+- User: "fix it" → "I see the issue - I'll fix that bug and make sure it doesn't break again."
+- User: "ok" → "Understood, moving forward with the changes."
+- User: "edit it" → "Got it, I'll make those edits to the file we were looking at."
+- User: "do it" → "On it - I'll implement what we discussed."
+- User: "hmm not sure" → "I understand the hesitation - let me explain the tradeoffs so you can decide."
+- User: "faster" → "Got it, I'll optimize the slow parts we identified."
+- User: "add tests" → "I'll add tests that cover the edge cases and prevent regressions."
+- User: "looks wrong" → "I see what you mean - let me fix that and double-check the logic."
+- User: "continue" → "Continuing from where we left off."
+- User: "try again" → "Got it, I'll retry with a different approach this time."

connectonion/prompts.py

@@ -19,7 +19,16 @@ DEFAULT_PROMPT = "You are a helpful assistant that can use tools to complete tas
 
 
 def _looks_like_file_path(text: str) -> bool:
-    """Check if a string looks like a file path rather than prompt text."""
+    """Check if a string looks like a file path rather than prompt text.
+
+    Returns False if the text is likely prompt content (contains newlines or is very long).
+    Returns True if the text looks like a file path (has path separators or prompt file extensions).
+    """
+    # Prompt text typically contains newlines and is longer than file paths
+    # File paths are single-line and limited by OS (usually < 1024 chars)
+    if '\n' in text or len(text) > 1024:
+        return False
+
     # Check for file extensions
     has_file_extension = '.' in text and text.split('.')[-1] in ['md', 'txt', 'prompt']
     # Check for path separators

connectonion/tui/chat.py

@@ -1,4 +1,13 @@
-"""Chat - Terminal chat interface using Textual.
+"""
+Purpose: Terminal chat interface using Textual framework for interactive agent conversations
+LLM-Note:
+  Dependencies: imports from [textual App/Screen/Widget, rich, core/agent.py, tui/input.py, tui/status_bar.py, tui/providers.py] | imported by [cli/commands/, examples/] | tested by [tests/tui/test_chat.py]
+  Data flow: Chat.run() starts Textual app → renders status bar + chat messages → Input widget captures user input → on_submit sends to agent.input() → agent response appended to message log → UI updates | supports slash command triggers with autocomplete providers
+  State/Effects: maintains message history in MessageLog widget | modifies terminal (clears screen, moves cursor) | restores terminal on exit | saves chat state in self.messages
+  Integration: exposes Chat(agent, title, triggers, welcome, hints, status_segments, input_placeholder) with run() method | CommandItem dataclass for slash commands | uses Textual's reactive system for live updates | integrates with Agent for LLM interactions
+  Performance: Textual async rendering (smooth) | message log scrolls efficiently | minimal re-renders via reactive
+  Errors: catches agent errors and displays in chat | restores terminal on crash | validates command triggers
+Chat - Terminal chat interface using Textual.
 
 A simple, clean chat UI that works with the terminal medium rather than
 fighting it. No fake "bubbles" - just clean text with color differentiation.

connectonion/tui/divider.py

@@ -1,4 +1,13 @@
-"""Divider - Simple horizontal line separator.
+"""
+Purpose: Simple horizontal line separator for terminal UI sections
+LLM-Note:
+  Dependencies: imports from [rich.text.Text] | imported by [tui/chat.py, tui/input.py] | tested by [tests/tui/test_divider.py]
+  Data flow: Divider(width, char, style) → render() → returns Rich Text with repeated character
+  State/Effects: no state (pure function)
+  Integration: exposes Divider(width, char, style) with render() → Text | used for visual separation in TUI layouts
+  Performance: trivial (string multiplication)
+  Errors: none
+Divider - Simple horizontal line separator.
 
 A minimal line to separate sections in terminal UI.
 """

connectonion/tui/dropdown.py

@@ -1,4 +1,13 @@
-"""Dropdown - reusable selection list component.
+"""
+Purpose: Reusable selection list component with fuzzy matching and keyboard navigation
+LLM-Note:
+  Dependencies: imports from [rich.text/table/console, tui/fuzzy.py, dataclasses] | imported by [tui/input.py, tui/providers.py] | tested by [tests/tui/test_dropdown.py]
+  Data flow: Dropdown(items, selected_index) → render() → formats items with icons/labels → highlights selected item → uses fuzzy.highlight_match() for query highlighting
+  State/Effects: maintains selected_index | no I/O (pure rendering)
+  Integration: exposes DropdownItem(icon, label, value, meta, score, positions) dataclass | Dropdown.render() → Rich Group | used by Input widget for autocomplete
+  Performance: renders visible items only | fuzzy highlighting is cached in positions
+  Errors: none (validates selected_index bounds)
+Dropdown - reusable selection list component.
 
 Modern zsh-style dropdown with icons and highlighting.
 """