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

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

@@ -0,0 +1,52 @@
+# Tool: Glob
+
+Fast file pattern matching for finding files by name.
+
+## When to Use
+
+- Find files by name pattern: `**/*.py`, `src/**/*.ts`
+- Locate specific file types across directories
+- Quick file discovery before reading
+
+## When NOT to Use
+
+- Searching file **contents** → use `grep` instead
+- Reading file contents → use `read_file` instead
+- Complex regex patterns → use `grep` instead
+
+## Pattern Syntax
+
+| Pattern | Matches |
+|---------|---------|
+| `*.py` | Python files in current dir |
+| `**/*.py` | Python files in all subdirs |
+| `src/**/*.ts` | TypeScript files under src/ |
+| `test_*.py` | Files starting with test_ |
+| `*.{js,ts}` | JS or TS files |
+
+## Guidelines
+
+- Returns file paths sorted by modification time (newest first)
+- Use for broad file discovery, then `read_file` for specific content
+- Prefer over bash `find` command
+
+## Examples
+
+<good-example>
+# Find all Python files
+glob("**/*.py")
+
+# Find test files
+glob("**/test_*.py")
+
+# Find config files
+glob("**/*.{json,yaml,toml}")
+</good-example>
+
+<bad-example>
+# Wrong: searching for content
+glob("import pandas")  # Use grep instead
+
+# Wrong: too broad
+glob("**/*")  # Be more specific
+</bad-example>

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

@@ -0,0 +1,55 @@
+# Tool: Grep
+
+Search file contents using regex patterns.
+
+## When to Use
+
+- Search for code patterns: `def my_function`, `class MyClass`
+- Find text across files
+- Locate imports, function calls, variable usage
+- Complex regex searches
+
+## When NOT to Use
+
+- Finding files by name → use `glob` instead
+- Reading entire file → use `read_file` instead
+- Simple filename matching → use `glob` instead
+
+## Capabilities
+
+- Full regex syntax support
+- Filter by file type or glob pattern
+- Multiple output modes:
+  - `files_with_matches` (default) - just file paths
+  - `content` - matching lines with context
+  - `count` - match counts per file
+
+## Guidelines
+
+- Start broad, narrow down if needed
+- Use with `-A`/`-B`/`-C` for context lines
+- Prefer over bash `grep` or `rg` commands
+
+## Examples
+
+<good-example>
+# Find function definition
+grep("def process_data")
+
+# Find class with context
+grep("class UserAuth", output_mode="content", C=3)
+
+# Find all imports of a module
+grep("from requests import", type="py")
+
+# Find TODO comments
+grep("TODO|FIXME", glob="**/*.py")
+</good-example>
+
+<bad-example>
+# Wrong: use glob for filename patterns
+grep("*.py")  # Use glob instead
+
+# Wrong: too broad, will match too much
+grep("the")  # Be more specific
+</bad-example>

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

@@ -0,0 +1,80 @@
+# Tool: Plan Mode
+
+Enter read-only planning phase to design implementation before coding.
+
+## When to Use
+
+- **New feature implementation** - needs design decisions
+- **Multiple valid approaches** - need to evaluate options
+- **Architectural decisions** - choosing patterns or technologies
+- **Multi-file changes** - touching more than 2-3 files
+- **Unclear requirements** - need to explore before understanding scope
+
+## When NOT to Use
+
+- Simple single-line fixes (typos, obvious bugs)
+- Adding a single function with clear requirements
+- User gave very specific, detailed instructions
+- Pure research tasks (use explore agent instead)
+
+## How It Works
+
+1. **Enter plan mode** with `enter_plan_mode()`
+2. **Explore codebase** using glob, grep, read_file (read-only)
+3. **Write plan** to `.co/PLAN.md` with `write_plan()`
+4. **Exit plan mode** with `exit_plan_mode()` when ready
+
+## READ-ONLY Restrictions
+
+In plan mode, you can ONLY:
+- Use glob, grep, read_file to explore
+- Write to the plan file
+- Ask user questions
+
+You CANNOT:
+- Modify any code files
+- Create new files
+- Run commands that change state
+
+## Plan File Format
+
+```markdown
+# Implementation Plan
+
+## Goal
+What we're trying to accomplish
+
+## Approach
+1. Step one
+2. Step two
+3. Step three
+
+## Files to Modify
+- src/auth.py - Add new handler
+- tests/test_auth.py - Add tests
+
+## Questions
+- Any clarifications needed?
+```
+
+## Examples
+
+<good-example>
+# Complex feature needs planning
+User: "Add user authentication"
+→ Enter plan mode, explore codebase, design approach
+
+# Multiple approaches possible
+User: "Optimize the database queries"
+→ Plan to profile and identify bottlenecks first
+</good-example>
+
+<bad-example>
+# Too simple for planning
+User: "Fix the typo in README"
+→ Just fix it directly
+
+# User gave specific instructions
+User: "Add console.log to line 42 of auth.py"
+→ Just do it, no planning needed
+</bad-example>

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

@@ -0,0 +1,40 @@
+# Tool: Read File
+
+Read file contents before making any modifications.
+
+## When to Use
+
+- **Always** before modifying an existing file
+- Understanding code patterns and conventions
+- Checking what libraries/dependencies exist
+- Understanding imports and surrounding code
+
+## Capabilities
+
+- Reads any file type (code, config, images, PDFs)
+- Returns content with line numbers (1-indexed)
+- Default: first 2000 lines
+- Use `offset` and `limit` for large files
+
+## Guidelines
+
+- Read the file BEFORE suggesting any changes
+- Look at imports to understand dependencies
+- Check for existing patterns in the codebase
+- Read related files to understand context
+
+## Examples
+
+<good-example>
+# Before editing auth.py, read it first
+read_file("src/auth.py")
+
+# Check dependencies before adding imports
+read_file("requirements.txt")
+read_file("package.json")
+</good-example>
+
+<bad-example>
+# Don't modify without reading first
+write("src/auth.py", "new content")  # Never do this!
+</bad-example>

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", "")