connectonion 0.6.1__py3-none-any.whl → 0.6.3__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/ui_stream.py

@@ -1,20 +1,17 @@
 """
-Purpose: Stream agent activity to UI via Connection API
+Purpose: Plugin for streaming agent completion summaries to WebSocket UI clients
 LLM-Note:
-  Dependencies: imports from [typing, core.events] | imported by [useful_plugins/__init__.py] | tested by [tests/unit/test_ui_stream.py]
-  Data flow: Event handlers check agent.connection → if present, call connection.log() to stream events
-  State/Effects: Streams events to WebSocket client | no file I/O | no blocking
-  Integration: exposes ui_stream list of event handlers | used via Agent(plugins=[ui_stream]) | works with host() WebSocket
-  Performance: O(1) event dispatch | no blocking | no LLM calls
-  Errors: Silently skips if connection is None (local execution)
-
-UI Stream Plugin - Stream agent activity to connected UI clients.
-
-When agent.connection is set (by host() for WebSocket connections), this plugin
-streams real-time events for:
-- LLM responses (thinking, tool_calls)
-- Tool execution (before/after each tool)
-- Errors and completion
+  Dependencies: imports from [core/events.py on_complete, typing] | imported by [useful_plugins/__init__.py, user code] | tested by [tests/plugins/test_ui_stream.py]
+  Data flow: fires on_complete event → extracts trace from current_session → counts tools_used and llm_calls → sends via agent.io.log('complete', tools_used, llm_calls, iterations) → WebSocket client receives completion event
+  State/Effects: sends message via agent.io (if connected) | no persistent state | read-only access to session trace
+  Integration: exposes ui_stream plugin (use via plugins=[ui_stream]) | only fires if agent.io exists (hosted mode) | complements direct events from agent.py/tool_executor.py | stream_complete handler decorated with @on_complete
+  Performance: minimal overhead (just counting trace entries) | single io.log call
+  Errors: returns early if no io connection | no exceptions raised
+UI Stream Plugin - Stream agent completion summary to connected UI clients.
+
+Events (user_input, thinking, tool_result, assistant) are now emitted directly
+from their source (agent.py, tool_executor.py, plugins). This plugin only
+handles the completion summary.
 
 Usage:
     from connectonion import Agent
@@ -25,128 +22,23 @@ Usage:
 """
 
 from typing import TYPE_CHECKING
-from ..core.events import (
-    after_llm,
-    before_each_tool,
-    after_each_tool,
-    on_error,
-    on_complete,
-)
+from ..core.events import on_complete
 
 if TYPE_CHECKING:
     from ..core.agent import Agent
 
 
-@after_llm
-def stream_llm_response(agent: 'Agent') -> None:
-    """Stream LLM response to connected UI."""
-    if not agent.connection:
-        return
-
-    trace = agent.current_session.get('trace', [])
-    if not trace:
-        return
-
-    last = trace[-1]
-    if last.get('type') != 'llm_call':
-        return
-
-    # Stream content if present
-    content = last.get('content', '')
-    if content:
-        agent.connection.log('message', content=content)
-
-    # Stream tool calls if present
-    tool_calls = last.get('tool_calls', [])
-    for tc in tool_calls:
-        agent.connection.log(
-            'tool_pending',
-            name=tc.get('function', {}).get('name', ''),
-            arguments=tc.get('function', {}).get('arguments', {}),
-            id=tc.get('id', ''),
-        )
-
-
-@before_each_tool
-def stream_tool_start(agent: 'Agent') -> None:
-    """Stream tool execution start to connected UI."""
-    if not agent.connection:
-        return
-
-    pending = agent.current_session.get('pending_tool')
-    if not pending:
-        return
-
-    agent.connection.log(
-        'tool_start',
-        name=pending['name'],
-        arguments=pending['arguments'],
-        id=pending.get('id', ''),
-    )
-
-
-@after_each_tool
-def stream_tool_result(agent: 'Agent') -> None:
-    """Stream tool execution result to connected UI."""
-    if not agent.connection:
-        return
-
-    trace = agent.current_session.get('trace', [])
-    if not trace:
-        return
-
-    last = trace[-1]
-    if last.get('type') != 'tool_execution':
-        return
-
-    status = last.get('status', 'unknown')
-    result = last.get('result', '')
-
-    # Truncate large results for UI
-    if isinstance(result, str) and len(result) > 1000:
-        result = result[:1000] + '...'
-
-    agent.connection.log(
-        'tool_result',
-        name=last.get('tool_name', ''),
-        status=status,
-        result=result,
-        timing_ms=last.get('timing', 0),
-    )
-
-
-@on_error
-def stream_error(agent: 'Agent') -> None:
-    """Stream error to connected UI."""
-    if not agent.connection:
-        return
-
-    trace = agent.current_session.get('trace', [])
-    if not trace:
-        return
-
-    last = trace[-1]
-    if last.get('status') != 'error':
-        return
-
-    agent.connection.log(
-        'error',
-        tool_name=last.get('tool_name', ''),
-        error=str(last.get('error', '')),
-    )
-
-
 @on_complete
 def stream_complete(agent: 'Agent') -> None:
-    """Stream completion to connected UI."""
-    if not agent.connection:
+    """Stream completion summary to connected UI."""
+    if not agent.io:
         return
 
     trace = agent.current_session.get('trace', [])
-    tools_used = [t.get('tool_name', '') for t in trace if t.get('type') == 'tool_execution']
+    tools_used = [t.get('name', '') for t in trace if t.get('type') == 'tool_result']
     llm_calls = len([t for t in trace if t.get('type') == 'llm_call'])
 
-    agent.connection.log(
+    agent.io.log(
         'complete',
         tools_used=tools_used,
         llm_calls=llm_calls,
@@ -154,11 +46,4 @@ def stream_complete(agent: 'Agent') -> None:
     )
 
 
-# Bundle as plugin
-ui_stream = [
-    stream_llm_response,
-    stream_tool_start,
-    stream_tool_result,
-    stream_error,
-    stream_complete,
-]
+ui_stream = [stream_complete]

connectonion/useful_prompts/README.md

@@ -0,0 +1,61 @@
+# useful_prompts
+
+Prompt examples and patterns for ConnectOnion agents. Copy what you need to your project.
+
+## Philosophy
+
+These are **examples**, not framework code. You:
+1. Browse the examples
+2. Copy what fits your needs
+3. Modify freely - you own the code now
+
+No lock-in. No rigid structure. Just good patterns.
+
+## Available Examples
+
+### coding_agent/
+A modular prompt structure for coding assistants.
+
+```
+coding_agent/
+├── prompts/
+│   ├── main.md           # Core agent behavior
+│   └── tools/            # Per-tool guidance
+│       ├── shell.md
+│       ├── read.md
+│       ├── write.md
+│       └── todo.md
+├── assembler.py          # Simple prompt assembly
+└── README.md
+```
+
+**Good for:** CLI coding assistants, code review bots, development helpers
+
+## How to Use
+
+```bash
+# Copy the example to your project
+cp -r useful_prompts/coding_agent/ my-project/
+
+# Customize the prompts
+cd my-project/coding_agent
+vim prompts/main.md       # Edit core behavior
+vim prompts/tools/shell.md # Edit shell guidance
+```
+
+## Creating Your Own
+
+1. Start with an existing example
+2. Modify `main.md` for your agent's personality
+3. Add/remove tool files as needed
+4. Customize `assembler.py` for your assembly logic
+
+## Principles
+
+From Claude Code's architecture, we learned:
+
+1. **Modular prompts** - Split by concern (main, per-tool)
+2. **"When NOT to use"** - As important as "when to use"
+3. **Examples with reasoning** - Show good AND bad patterns
+4. **Assembly at runtime** - Combine pieces based on available tools
+5. **User owns the code** - No framework lock-in

connectonion/useful_prompts/__init__.py

@@ -0,0 +1,45 @@
+"""
+Purpose: Prompt templates directory with utility for copying example prompts to user projects
+LLM-Note:
+  Dependencies: imports from [pathlib] | imported by [cli/commands/copy_commands.py, user code] | tested by [tests/prompts/test_useful_prompts.py]
+  Data flow: get_example_path(name) → returns Path to template directory for copying | PROMPTS_DIR constant points to useful_prompts/ directory
+  State/Effects: reads filesystem (Path operations) | no modifications
+  Integration: exposes PROMPTS_DIR constant, get_example_path(name) → Path | used by `co copy coding_agent` command to copy templates | contains coding_agent/ subdirectory with main.md, tools/*.md, assembler.py
+  Performance: trivial (Path operations only)
+  Errors: none (Path returned whether directory exists or not, caller handles)
+useful_prompts - Prompt templates for ConnectOnion agents.
+
+These are PROMPT TEMPLATES to copy to your project, not framework code to import.
+
+Usage:
+    1. Run: co copy coding_agent
+    2. Customize the markdown files in prompts/coding_agent/
+    3. Use assembler.py to build your system prompt
+
+Available prompts:
+    - coding_agent/  : Coding Agent Prompt - modular template for coding assistants
+
+See README.md for details.
+"""
+
+from pathlib import Path
+
+# Path to useful_prompts directory (for copying examples)
+PROMPTS_DIR = Path(__file__).parent
+
+
+def get_example_path(name: str) -> Path:
+    """Get path to an example directory for copying.
+
+    Args:
+        name: Example name (e.g., "coding_agent")
+
+    Returns:
+        Path to the example directory
+
+    Example:
+        >>> from connectonion.useful_prompts import get_example_path
+        >>> import shutil
+        >>> shutil.copytree(get_example_path("coding_agent"), "my_prompts")
+    """
+    return PROMPTS_DIR / name