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

connectonion/useful_plugins/re_act.py

@@ -1,20 +1,24 @@
 """
-Purpose: ReAct (Reasoning + Acting) plugin that adds planning and reflection to agent execution
+Purpose: ReAct (Reasoning + Acting) plugin that adds intent recognition and reflection to agent execution
 LLM-Note:
-  Dependencies: imports from [pathlib, typing, events.after_user_input, llm_do, useful_events_handlers.reflect] | imported by [useful_plugins/__init__.py] | uses prompt file [prompt_files/react_plan.md] | tested by [tests/unit/test_re_act_plugin.py]
-  Data flow: after_user_input → plan_task() generates a plan using llm_do() → stores in agent.current_session['plan'] → after_tools → reflect() from useful_events_handlers evaluates results → generates reflection for next step
-  State/Effects: modifies agent.current_session['plan'] and ['expected'] | makes LLM calls for planning and reflection | no file I/O | no network besides LLM
-  Integration: exposes re_act plugin list with [plan_task, reflect] event handlers | used via Agent(plugins=[re_act]) | works with eval plugin for debugging
-  Performance: 1-2 LLM calls per turn (plan + reflect) | adds latency but improves agent reasoning
+  Dependencies: imports from [pathlib, typing, events.after_user_input, llm_do, useful_events_handlers.reflect] | imported by [useful_plugins/__init__.py] | uses prompt file [prompt_files/react_acknowledge.md] | tested by [tests/unit/test_re_act_plugin.py]
+  Data flow: after_user_input → acknowledge_request() → after_tools → reflect()
+  State/Effects: modifies agent.current_session['intent'] | makes LLM calls for intent, reflection | no file I/O
+  Integration: exposes re_act plugin list with [acknowledge_request, reflect] event handlers | used via Agent(plugins=[re_act])
+  Performance: 2 LLM calls per turn (intent + reflect) | adds latency but improves agent reasoning
   Errors: no explicit error handling | LLM failures propagate | silent skip if no user_prompt
 
 ReAct plugin - Reasoning and Acting pattern for AI agents.
 
-Implements the ReAct (Reason + Act) pattern:
-1. After user input: Plan what to do
-2. After tool execution: Reflect on results and plan next step
+Implements a simplified ReAct pattern:
+1. After user input: Acknowledge request (show we understood)
+2. After tool execution: Reflect on results
 
-For evaluation/debugging, use the separate `eval` plugin.
+Planning is left to the main agent - this plugin just adds intent recognition and reflection.
+
+Trace kinds for frontend rendering:
+- kind='intent' → Show as "Understanding..." card
+- kind='reflect' → Show as "Reflecting..." card
 
 Usage:
     from connectonion import Agent
@@ -37,42 +41,124 @@ if TYPE_CHECKING:
     from ..core.agent import Agent
 
 # Prompts
-PLAN_PROMPT = Path(__file__).parent.parent / "prompt_files" / "react_plan.md"
+ACKNOWLEDGE_PROMPT = Path(__file__).parent.parent / "prompt_files" / "react_acknowledge.md"
+
+
+def _format_conversation(
+    messages: list,
+    max_tokens: int = 4000,
+    max_messages: int = 50,
+) -> str:
+    """Format conversation history with smart truncation.
+
+    Only truncates when context exceeds budget. Priorities:
+    1. User messages: always kept full (important context)
+    2. Recent assistant messages: kept longer
+    3. Older assistant messages: truncated first
+
+    Args:
+        messages: List of message dicts with 'role' and 'content'
+        max_tokens: Approximate token budget (~4 chars per token)
+        max_messages: Max number of messages to consider
+    """
+    max_chars = max_tokens * 4  # ~4 chars per token approximation
+
+    recent = messages[-max_messages:] if len(messages) > max_messages else messages
+    if not recent:
+        return ""
+
+    # First pass: calculate total size with full messages
+    total_chars = sum(len(m.get('content', '')) for m in recent)
+
+    # If under budget, return everything full
+    if total_chars <= max_chars:
+        lines = []
+        for msg in recent:
+            role = msg.get('role', 'unknown')
+            content = msg.get('content', '')
+            if content:
+                lines.append(f"{role}: {content}")
+        return "\n".join(lines)
+
+    # Over budget: smart truncation
+    # User messages kept full, truncate assistant messages
+    user_chars = sum(len(m.get('content', '')) for m in recent if m.get('role') == 'user')
+    available_for_assistant = max_chars - user_chars
+
+    assistant_msgs = [m for m in recent if m.get('role') == 'assistant' and m.get('content')]
+    if not assistant_msgs:
+        return "\n".join(f"user: {m.get('content', '')}" for m in recent if m.get('role') == 'user')
+
+    # Distribute chars to assistant messages (more to recent ones)
+    n = len(assistant_msgs)
+    weights = [1 + (i / n) for i in range(n)]  # older=1.0, recent=~2.0
+    total_weight = sum(weights)
+    char_budgets = [int(available_for_assistant * w / total_weight) for w in weights]
+
+    # Build output
+    lines = []
+    assistant_idx = 0
+    for msg in recent:
+        role = msg.get('role', 'unknown')
+        content = msg.get('content', '')
+        if not content:
+            continue
+
+        if role == 'user':
+            lines.append(f"user: {content}")
+        elif role == 'assistant':
+            budget = char_budgets[assistant_idx] if assistant_idx < len(char_budgets) else 200
+            assistant_idx += 1
+            if len(content) > budget:
+                content = content[:budget] + "..."
+            lines.append(f"assistant: {content}")
+
+    return "\n".join(lines)
 
 
 @after_user_input
-def plan_task(agent: 'Agent') -> None:
-    """Plan the task after receiving user input."""
+def acknowledge_request(agent: 'Agent') -> None:
+    """Immediately acknowledge the user's request to show we understood."""
     user_prompt = agent.current_session.get('user_prompt', '')
     if not user_prompt:
         return
 
-    tool_names = agent.tools.names() if agent.tools else []
-    tools_str = ", ".join(tool_names) if tool_names else "no tools"
+    # Include conversation history for context
+    messages = agent.current_session.get('messages', [])
+    conversation = _format_conversation(messages)
 
-    prompt = f"""User request: {user_prompt}
+    prompt = f"""Conversation so far:
+{conversation}
 
-Available tools: {tools_str}
+Current user input: {user_prompt}
 
-Brief plan (1-2 sentences): what to do first?"""
+Acknowledge this request (1-2 sentences):"""
 
-    agent.logger.print("[dim]/planning...[/dim]")
+    model = "co/gemini-2.5-flash"
+    agent.logger.print(f"[dim]/understanding ({model})...[/dim]")
 
-    plan = llm_do(
+    ack = llm_do(
         prompt,
-        model="co/gemini-2.5-flash",
-        temperature=0.2,
-        system_prompt=PLAN_PROMPT
+        model=model,
+        temperature=0.3,
+        system_prompt=ACKNOWLEDGE_PROMPT
     )
 
-    # Store plan as expected outcome (used by eval plugin if present)
-    agent.current_session['expected'] = plan
+    agent.current_session['intent'] = ack
+
+    agent._record_trace({
+        'type': 'thinking',
+        'kind': 'intent',
+        'content': ack,
+    })
 
+    # Add to messages so LLM sees the understanding
     agent.current_session['messages'].append({
         'role': 'assistant',
-        'content': f"💭 {plan}"
+        'content': ack
     })
 
 
-# Bundle as plugin: plan (after_user_input) + reflect (after_tools)
-re_act = [plan_task, reflect]
+# Bundle as plugin: acknowledge (after_user_input) + reflect (after_tools)
+# Planning is handled by the main agent
+re_act = [acknowledge_request, reflect]

connectonion/useful_plugins/shell_approval.py

@@ -105,9 +105,9 @@ def _check_approval(agent: 'Agent') -> None:
     if not pending:
         return
 
-    # Only check bash/shell tools
+    # Only check bash/shell tools (including run_in_dir)
     tool_name = pending['name']
-    if tool_name not in ('bash', 'shell', 'run'):
+    if tool_name not in ('bash', 'shell', 'run', 'run_in_dir'):
         return
 
     # Get command from arguments

connectonion/useful_plugins/system_reminder.py

@@ -0,0 +1,103 @@
+"""
+System Reminder Plugin - Injects contextual guidance into tool results.
+
+Usage:
+    from connectonion.useful_plugins import system_reminder
+    agent = Agent("assistant", plugins=[system_reminder])
+
+To customize, use `co copy system_reminder` which copies both the plugin
+and the prompt files to your project.
+"""
+
+from pathlib import Path
+import fnmatch
+from typing import TYPE_CHECKING
+
+from ..core.events import after_each_tool
+
+if TYPE_CHECKING:
+    from ..core.agent import Agent
+
+# Default reminders directory
+REMINDERS_DIR = Path(__file__).parent.parent / "useful_prompts" / "system-reminders"
+
+
+def _parse_frontmatter(text):
+    """Parse YAML frontmatter from markdown."""
+    if not text.startswith('---'):
+        return {}, text
+    parts = text.split('---', 2)
+    if len(parts) < 3:
+        return {}, text
+    import yaml
+    return yaml.safe_load(parts[1]) or {}, parts[2].strip()
+
+
+def _load_reminders(reminders_dir):
+    """Load all .md reminder files from directory."""
+    reminders_dir = Path(reminders_dir)
+    if not reminders_dir.exists():
+        return {}
+    reminders = {}
+    for f in reminders_dir.glob("*.md"):
+        meta, body = _parse_frontmatter(f.read_text())
+        if meta.get('name'):
+            reminders[meta['name']] = {'content': body, 'triggers': meta.get('triggers', [])}
+    return reminders
+
+
+def _matches_pattern(pattern, value):
+    """Check if value matches glob pattern(s)."""
+    if not pattern or not value:
+        return False
+    patterns = [pattern] if isinstance(pattern, str) else pattern
+    return any(fnmatch.fnmatch(value, p) for p in patterns)
+
+
+def _find_reminder(reminders, tool_name, args):
+    """Find matching reminder content."""
+    for reminder in reminders.values():
+        for trigger in reminder['triggers']:
+            if trigger.get('tool') and trigger['tool'] != tool_name:
+                continue
+            if trigger.get('path_pattern'):
+                path = args.get('path') or args.get('file_path', '')
+                if not _matches_pattern(trigger['path_pattern'], path):
+                    continue
+            if trigger.get('command_pattern'):
+                cmd = args.get('command') or args.get('cmd', '')
+                if not _matches_pattern(trigger['command_pattern'], cmd):
+                    continue
+            # All conditions matched
+            content = reminder['content']
+            path = args.get('path') or args.get('file_path', '')
+            return content.replace('${file_path}', path).replace('${tool_name}', tool_name)
+    return None
+
+
+# Load reminders once at import
+_REMINDERS = _load_reminders(REMINDERS_DIR)
+
+
+@after_each_tool
+def inject_reminder(agent: 'Agent') -> None:
+    """Inject matching system reminder into tool result."""
+    trace = agent.current_session.get('trace', [])
+    messages = agent.current_session.get('messages', [])
+    if not trace or not messages:
+        return
+
+    last = trace[-1]
+    if last.get('type') != 'tool_result':
+        return
+
+    content = _find_reminder(_REMINDERS, last.get('name', ''), last.get('args', {}))
+    if content:
+        for msg in reversed(messages):
+            if msg.get('role') == 'tool':
+                msg['content'] = msg.get('content', '') + '\n\n' + content
+                break
+
+
+# Export plugin
+system_reminder = [inject_reminder]

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]