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

connectonion/cli/co_ai/prompts/tools/background.md

@@ -0,0 +1,57 @@
+# Tool: Background Tasks
+
+Run long-running commands in the background.
+
+## When to Use
+
+- **Long builds** - `npm run build`, `cargo build`
+- **Dev servers** - `npm run dev`, `python manage.py runserver`
+- **Watch modes** - `npm run watch`, `pytest --watch`
+- **Any command** that runs indefinitely or takes >30 seconds
+
+## When NOT to Use
+
+- Quick commands (<30 seconds)
+- Commands you need immediate results from
+- One-off queries
+
+## Available Functions
+
+| Function | Purpose |
+|----------|---------|
+| `run_background(cmd)` | Start a background task, returns task_id |
+| `task_output(task_id)` | Get output from running task |
+| `kill_task(task_id)` | Stop a background task |
+
+## Guidelines
+
+- Save the task_id to check output later
+- Use `task_output()` to monitor progress
+- Remember to `kill_task()` when done with dev servers
+- Background tasks persist until killed or session ends
+
+## Examples
+
+<good-example>
+# Start dev server
+task_id = run_background("npm run dev")
+
+# Check output later
+output = task_output(task_id)
+
+# Stop when done
+kill_task(task_id)
+
+# Long build
+task_id = run_background("cargo build --release")
+# Continue with other work...
+output = task_output(task_id, block=True)  # Wait for completion
+</good-example>
+
+<bad-example>
+# Too quick - just run directly
+run_background("ls")
+
+# Need immediate result
+run_background("git status")  # Just run normally
+</bad-example>

connectonion/cli/co_ai/prompts/tools/edit.md

@@ -0,0 +1,90 @@
+# Tool: Edit
+
+Perform exact string replacements in existing files.
+
+## When to Use
+
+- Modifying existing files
+- Changing specific code sections
+- Renaming variables or functions
+- Updating configuration values
+
+## When NOT to Use
+
+- Creating new files → use `write` instead
+- Replacing entire file contents → use `write` instead
+- Reading files → use `read` first
+
+## CRITICAL: Read Before Edit
+
+**You MUST read a file before editing it.** This is a blocking requirement.
+
+The Edit tool will fail if you haven't read the file first. Always:
+1. Read the file with `read`
+2. Understand the content and structure
+3. Then use `edit` for modifications
+
+## How It Works
+
+The Edit tool performs **exact string replacement**:
+- `old_string`: The exact text to find (must be unique in file)
+- `new_string`: The replacement text
+- `replace_all`: Set to `true` to replace all occurrences (useful for renaming)
+
+## Guidelines
+
+### Preserve Indentation
+Copy the exact indentation from the Read output. The Read tool shows content with line numbers like:
+```
+    42→    def my_function():
+    43→        return True
+```
+Everything AFTER the `→` is the actual file content. Match that indentation exactly.
+
+### Never Include Line Numbers
+The line number prefix (e.g., `    42→`) is NOT part of the file. Never include it in `old_string` or `new_string`.
+
+### Make old_string Unique
+If `old_string` appears multiple times, the edit will fail. Include enough surrounding context to make it unique:
+
+<bad-example>
+old_string: "return True"  # Too common, might match multiple places
+</bad-example>
+
+<good-example>
+old_string: "def validate_user():\n    return True"  # Unique context
+</good-example>
+
+### Use replace_all for Renaming
+When renaming a variable or function across a file:
+```
+old_string: "oldName"
+new_string: "newName"
+replace_all: true
+```
+
+### Prefer Edit Over Write
+Always prefer editing existing files over creating new ones. Small, targeted changes are safer than full file rewrites.
+
+## Examples
+
+<good-example>
+# Read file first
+[read file.py]
+
+# Then edit with exact match
+old_string: "def old_function():\n    pass"
+new_string: "def new_function():\n    return 42"
+</good-example>
+
+<bad-example>
+# Editing without reading first - WILL FAIL
+[edit file.py without reading]
+
+# Including line numbers - WRONG
+old_string: "   42→    def my_func():"
+
+# Changing indentation - breaks the code
+old_string: "    return True"
+new_string: "return True"  # Lost indentation
+</bad-example>

connectonion/cli/co_ai/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/cli/co_ai/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/cli/co_ai/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/cli/co_ai/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/cli/co_ai/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_TOOL_NAME or "read_file"}` instead
+- Writing files → use `${WRITE_TOOL_NAME or "write"}` instead
+- Searching file contents → use `${GREP_TOOL_NAME or "grep"}` instead
+
+## Guidelines
+
+- Use absolute paths when possible to avoid `cd` confusion
+- Chain dependent commands with `&&`: `git add . && git commit -m "msg"`
+- Output is truncated at ${MAX_OUTPUT_CHARS or "30000"} characters
+- Default timeout: ${TIMEOUT_SECONDS or "120"} seconds
+
+### 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_TOOL_NAME or "read_file"} instead
+echo "content" > file       # Use ${WRITE_TOOL_NAME or "write"} instead
+cd /foo && pytest           # Use absolute path instead
+cd /path/with spaces        # Missing quotes - will fail
+</bad-example>

connectonion/cli/co_ai/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/cli/co_ai/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/cli/co_ai/prompts/tools/write.md

@@ -0,0 +1,47 @@
+# 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>
+# BOTH path and content are REQUIRED
+write(path="/tmp/agent.py", content="from connectonion import Agent\n...")
+write(path="src/utils.py", content="def helper(): ...")
+</good-example>
+
+<bad-example>
+# Missing content - will error
+write(path="/tmp/agent.py")  # WRONG: missing content!
+</bad-example>