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

connectonion/useful_prompts/coding_agent/prompts/tools/shell.md

@@ -0,0 +1,67 @@
+# Tool: Shell
+
+Execute terminal commands in a persistent shell session.
+
+## When to Use
+
+- Git operations: `git status`, `git add`, `git commit`, `git push`
+- Package management: `npm install`, `pip install`, `cargo build`
+- Running tests: `pytest`, `npm test`, `cargo test`
+- Directory operations: `ls`, `mkdir`, `tree`
+- Build commands: `npm run build`, `make`
+- Any other shell command
+
+## When NOT to Use
+
+- Reading file contents → use `read_file` instead
+- Writing files → use `write` instead
+- Searching file contents → read files directly
+
+## Guidelines
+
+- Use absolute paths when possible to avoid `cd` confusion
+- Chain dependent commands with `&&`: `git add . && git commit -m "msg"`
+- Output is truncated at 30000 characters
+- Default timeout: 2 minutes
+
+### Path Quoting (REQUIRED)
+Always quote paths with spaces using double quotes:
+```bash
+cd "/Users/name/My Documents"     # Correct
+python "/path/with spaces/run.py" # Correct
+cd /Users/name/My Documents       # WRONG - will fail
+```
+
+### Directory Verification
+Before creating files/directories, verify the parent exists:
+```bash
+ls /foo           # Verify /foo exists
+mkdir /foo/bar    # Now safe to create
+```
+
+### Parallel vs Sequential
+- **Independent commands**: Call tool multiple times in parallel
+- **Dependent commands**: Chain with `&&` in single call
+```bash
+# Sequential (dependent)
+git add . && git commit -m "msg" && git push
+
+# Parallel (independent) - use separate tool calls
+[git status] [git diff] [git log]
+```
+
+## Examples
+
+<good-example>
+pytest /foo/bar/tests
+git status
+npm run build
+cd "/path/with spaces" && ls
+</good-example>
+
+<bad-example>
+cat file.txt                # Use read_file instead
+echo "content" > file       # Use write instead
+cd /foo && pytest           # Use absolute path instead
+cd /path/with spaces        # Missing quotes - will fail
+</bad-example>

connectonion/useful_prompts/coding_agent/prompts/tools/task.md

@@ -0,0 +1,51 @@
+# Tool: Task
+
+Launch specialized sub-agents for complex investigations.
+
+## When to Use
+
+- **Codebase exploration** - "Find all API endpoints"
+- **Multi-file analysis** - "How does auth work?"
+- **Architecture questions** - "What's the project structure?"
+- **Complex searches** requiring multiple rounds of glob/grep
+
+## When NOT to Use
+
+- Simple file reads → use `read_file` instead
+- Specific known file → use `read_file` instead
+- Quick single search → use `glob` or `grep` directly
+
+## Available Agents
+
+| Agent | Purpose |
+|-------|---------|
+| `explore` | Fast codebase navigation and search |
+| `plan` | Design implementation approach |
+
+## Guidelines
+
+- Use explore agent for open-ended codebase questions
+- Provide clear, specific task descriptions
+- Let the agent work autonomously - it has its own tools
+- Trust the agent's findings
+
+## Examples
+
+<good-example>
+# Explore codebase structure
+task("explore", "Find all API endpoints and their handlers")
+
+# Understand a feature
+task("explore", "How does the authentication system work?")
+
+# Search for patterns
+task("explore", "Find all database queries and their locations")
+</good-example>
+
+<bad-example>
+# Too simple - just use grep directly
+task("explore", "Find class MyClass")
+
+# Specific file - just read it
+task("explore", "Read src/auth.py")
+</bad-example>

connectonion/useful_prompts/coding_agent/prompts/tools/todo.md

@@ -0,0 +1,139 @@
+# Tool: Todo List
+
+Track tasks and progress for complex multi-step work. Helps users understand your progress.
+
+## When to Use
+
+Use this tool proactively when:
+1. **Complex multi-step tasks** - 3 or more distinct steps
+2. **User provides multiple tasks** - numbered or comma-separated list
+3. **Non-trivial work** - requires careful planning
+4. **After receiving new instructions** - capture requirements immediately
+5. **When starting work** - mark as `in_progress` BEFORE beginning
+
+## When NOT to Use
+
+Skip this tool when:
+1. Single, straightforward task
+2. Trivial operations (fix typo, add one line)
+3. Task can be completed in less than 3 trivial steps
+4. Pure Q&A or informational requests
+
+## Task Format (REQUIRED)
+
+Each task MUST have two forms:
+- **content**: Imperative form ("Run tests", "Fix the bug")
+- **activeForm**: Present continuous ("Running tests", "Fixing the bug")
+
+```json
+{
+  "content": "Run tests",
+  "activeForm": "Running tests",
+  "status": "pending"
+}
+```
+
+## Task States
+
+- `pending` - Not yet started
+- `in_progress` - Currently working (exactly ONE at a time)
+- `completed` - Finished successfully
+
+## Strict Rules
+
+1. **Exactly ONE task in_progress** at any time (not less, not more)
+2. **Mark complete IMMEDIATELY** after finishing (don't batch)
+3. **Only complete when FULLY done** - never if:
+   - Tests are failing
+   - Implementation is partial
+   - Errors are unresolved
+4. **If blocked**: Keep in_progress and create a new task for the blocker
+
+## Examples: When to Use
+
+<example>
+User: "Add dark mode toggle and run tests when done"
+
+Assistant creates todo list:
+1. Read existing settings page code
+2. Add dark mode toggle component
+3. Add dark mode state management
+4. Update styles for dark theme
+5. Run tests and fix any failures
+
+<reasoning>
+Used todo list because:
+1. Multi-step feature (UI, state, styling)
+2. User explicitly requested tests afterward
+3. Inferred tests need to pass as final step
+</reasoning>
+</example>
+
+<example>
+User: "Rename getCwd to getCurrentWorkingDirectory across the project"
+
+Assistant first searches codebase, finds 15 instances in 8 files.
+Then creates todo list with specific items for each file.
+
+<reasoning>
+Used todo list because:
+1. First searched to understand scope
+2. Found multiple occurrences across files
+3. Todo ensures every instance is tracked
+4. Prevents missing any occurrences
+</reasoning>
+</example>
+
+<example>
+User: "Implement user registration, product catalog, shopping cart, and checkout"
+
+Assistant creates todo list breaking down each feature.
+
+<reasoning>
+Used todo list because:
+1. User provided multiple complex features
+2. Organizes large work into manageable tasks
+3. Allows tracking progress across implementation
+</reasoning>
+</example>
+
+## Examples: When NOT to Use
+
+<example>
+User: "How do I print 'Hello World' in Python?"
+
+Assistant answers directly without todo list.
+
+<reasoning>
+Did NOT use todo list because:
+- Single, trivial task
+- No multiple steps to track
+- Just informational
+</reasoning>
+</example>
+
+<example>
+User: "Fix the typo in README"
+
+Assistant fixes it directly without todo list.
+
+<reasoning>
+Did NOT use todo list because:
+- Single straightforward task
+- One location in code
+- No tracking needed
+</reasoning>
+</example>
+
+<example>
+User: "Run npm install"
+
+Assistant runs command directly.
+
+<reasoning>
+Did NOT use todo list because:
+- Single command execution
+- Immediate results
+- No multiple steps
+</reasoning>
+</example>

connectonion/useful_prompts/coding_agent/prompts/tools/write.md

@@ -0,0 +1,48 @@
+# Tool: Write File
+
+Write files with colorized diff display and user approval.
+
+## Approval Flow
+
+```
+╭─── Changes to hello.py ────────────────────────╮
+│ --- a/hello.py                                 │
+│ +++ b/hello.py                                 │
+│ @@ -1,2 +1,3 @@                                │
+│  def hello():                                  │
+│ -    pass                                      │
+│ +    print("Hello, World!")                    │
+╰────────────────────────────────────────────────╯
+
+❯ 1 - Yes, apply this change
+  2 - Yes to all (auto-approve for session)
+  3 - No, and tell agent what to do instead
+```
+
+## Guidelines
+
+- **Always read the file first** before writing
+- Creates parent directories automatically if needed
+- Returns byte count on success
+- If rejected, user feedback is returned for you to retry
+
+## Best Practices
+
+- Match existing code style exactly
+- Keep changes minimal and focused
+- Don't add comments unless asked
+- Don't refactor unrelated code
+
+## Examples
+
+<good-example>
+# Read first, then write
+content = read_file("src/utils.py")
+# ... analyze content ...
+write("src/utils.py", modified_content)
+</good-example>
+
+<bad-example>
+# Writing without reading - don't do this
+write("src/utils.py", completely_new_content)
+</bad-example>

connectonion/useful_prompts/system-reminders/security-warning.md

@@ -0,0 +1,14 @@
+---
+name: security-warning
+triggers:
+  - tool: read_file
+    path_pattern: ["*.env", "*secret*", "*credential*", "*.pem", "*.key"]
+  - tool: read
+    path_pattern: ["*.env", "*secret*", "*credential*"]
+---
+
+<system-reminder>
+This file may contain sensitive information.
+- Never expose secrets in output
+- Never commit real credentials
+</system-reminder>

connectonion/useful_prompts/system-reminders/test-reminder.md

@@ -0,0 +1,11 @@
+---
+name: test-reminder
+triggers:
+  - tool: write_file
+    path_pattern: ["*.py", "*.js", "*.ts"]
+---
+
+<system-reminder>
+Code was modified. Consider running tests to verify changes.
+This is a gentle reminder - ignore if not applicable.
+</system-reminder>

connectonion/useful_tools/__init__.py

@@ -1,10 +1,10 @@
 """
 Purpose: Export all useful tools and utilities for ConnectOnion agents
 LLM-Note:
-  Dependencies: imports from [send_email, get_emails, memory, gmail, google_calendar, outlook, microsoft_calendar, web_fetch, shell, diff_writer, tui.pick, terminal, todo_list, slash_command] | imported by [__init__.py main package] | re-exports tools for agent consumption
+  Dependencies: imports from [send_email, get_emails, memory, gmail, google_calendar, outlook, microsoft_calendar, web_fetch, shell, diff_writer, tui.pick, terminal, todo_list, slash_command, read_file, edit, multi_edit, glob_files, grep_files, write_file] | imported by [__init__.py main package] | re-exports tools for agent consumption
   Data flow: agent imports from useful_tools → accesses tool functions/classes directly
   State/Effects: no state | pure re-exports | lazy loading for heavy dependencies
-  Integration: exposes send_email, get_emails, mark_read, mark_unread (email functions) | Memory, Gmail, GoogleCalendar, Outlook, MicrosoftCalendar, WebFetch, Shell, DiffWriter, TodoList (tool classes) | pick, yes_no, autocomplete (TUI helpers) | SlashCommand (extension point)
+  Integration: exposes send_email, get_emails, mark_read, mark_unread (email functions) | Memory, Gmail, GoogleCalendar, Outlook, MicrosoftCalendar, WebFetch, Shell, DiffWriter, TodoList (tool classes) | pick, yes_no, autocomplete (TUI helpers) | SlashCommand (extension point) | read_file, edit, multi_edit, glob, grep, write, Write (Claude Code-style tools)
   Errors: ImportError if dependency not installed (e.g., google-auth for GoogleCalendar, httpx for Outlook/MicrosoftCalendar)
 """
 
@@ -17,17 +17,29 @@ from .outlook import Outlook
 from .microsoft_calendar import MicrosoftCalendar
 from .web_fetch import WebFetch
 from .shell import Shell
-from .diff_writer import DiffWriter
+from .bash import bash
+from .diff_writer import DiffWriter, MODE_NORMAL, MODE_AUTO, MODE_PLAN
 from ..tui import pick
 from .terminal import yes_no, autocomplete
 from .todo_list import TodoList
 from .slash_command import SlashCommand
+from .ask_user import ask_user
+
+# Claude Code-style file tools
+from .read_file import read_file
+from .edit import edit
+from .multi_edit import multi_edit
+from .glob_files import glob
+from .grep_files import grep
+from .write_file import write, FileWriter
 
 __all__ = [
+    # Email tools
     "send_email",
     "get_emails",
     "mark_read",
     "mark_unread",
+    # Class-based tools
     "Memory",
     "Gmail",
     "GoogleCalendar",
@@ -35,10 +47,25 @@ __all__ = [
     "MicrosoftCalendar",
     "WebFetch",
     "Shell",
+    "bash",
     "DiffWriter",
+    "MODE_NORMAL",
+    "MODE_AUTO",
+    "MODE_PLAN",
+    # TUI helpers
     "pick",
     "yes_no",
     "autocomplete",
+    # Task management
     "TodoList",
-    "SlashCommand"
+    "SlashCommand",
+    "ask_user",
+    # Claude Code-style file tools
+    "read_file",
+    "edit",
+    "multi_edit",
+    "glob",
+    "grep",
+    "write",
+    "FileWriter",
 ]

connectonion/useful_tools/ask_user.py

@@ -0,0 +1,35 @@
+"""
+Purpose: Ask user a question during agent execution via io
+LLM-Note:
+  Dependencies: imports from [typing] | imported by [useful_tools/__init__.py]
+  Data flow: agent calls ask_user tool → sends ask_user event via io → waits for response → returns answer
+  State/Effects: blocks until user responds via io
+  Integration: requires agent.io to be set | agent parameter injected by tool_executor
+"""
+
+from typing import List, Optional
+
+
+def ask_user(
+    agent,
+    question: str,
+    options: Optional[List[str]] = None,
+    multi_select: bool = False
+) -> str:
+    """Ask the user a question and wait for their response.
+
+    Args:
+        question: The question to ask the user
+        options: Optional list of choices for the user to select from
+        multi_select: If True, user can select multiple options
+
+    Returns:
+        The user's answer (or comma-separated answers if multi_select)
+    """
+    agent.io.send({
+        "type": "ask_user",
+        "question": question,
+        "options": options,
+        "multi_select": multi_select
+    })
+    return agent.io.receive().get("answer", "")

connectonion/useful_tools/bash.py

@@ -0,0 +1,69 @@
+"""
+Bash tool for executing terminal commands (Unix/Mac only).
+
+Usage:
+    from connectonion import Agent, bash
+
+    agent = Agent("coder", tools=[bash])
+
+    # Agent can now use:
+    # - bash(command) - Execute bash command, returns output
+    # - bash(command, cwd="/path") - Execute in specific directory
+    # - bash(command, timeout=60) - Execute with custom timeout
+
+Note: This tool is for Unix/Mac systems. For cross-platform usage, use Shell class instead.
+"""
+
+import subprocess
+import platform
+
+
+def bash(command: str, cwd: str = ".", timeout: int = 120) -> str:
+    """Execute a bash command, returns output (Unix/Mac only).
+
+    Args:
+        command: Bash command to execute (e.g., "ls -la", "git status")
+        cwd: Working directory (default: current directory)
+        timeout: Seconds before timeout (default: 120, max: 600)
+
+    Returns:
+        Command output (stdout + stderr)
+    """
+    # Check platform
+    if platform.system() == "Windows":
+        return "Error: bash tool is for Unix/Mac only. Use Shell class for Windows."
+
+    # Cap timeout at 10 minutes
+    timeout = min(timeout, 600)
+
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            executable="/bin/bash",
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=timeout
+        )
+    except subprocess.TimeoutExpired:
+        return f"Error: Command timed out after {timeout} seconds"
+    except FileNotFoundError:
+        return "Error: /bin/bash not found. This tool requires bash shell."
+
+    parts = []
+    if result.stdout:
+        parts.append(result.stdout.rstrip())
+    if result.stderr:
+        parts.append(f"STDERR:\n{result.stderr.rstrip()}")
+    if result.returncode != 0:
+        parts.append(f"\nExit code: {result.returncode}")
+
+    output = "\n".join(parts) if parts else "(no output)"
+
+    # Truncate large outputs
+    max_chars = 10000
+    if len(output) > max_chars:
+        output = output[:max_chars] + f"\n... (truncated, {len(output):,} total chars)"
+
+    return output