Edit: Encourage cat > EOF multiline edits for code and documentation
deci committed
May 13, 2025 at 00:15 UTC
929ea8515835158feaf3e9dce9160f810bbe9de5
2 files changed
+83
-51
prompts/default/agent.system.tool.code_exe.md
+55
-35
@@ -133,41 +133,61 @@ Execute commands and code for computation, data analysis, and file operations.
133
### FILE EDITING BEST PRACTICES
134
When editing files, especially code files:
135
136
-1. ALWAYS use the "read entire file → modify in memory → write entire file" pattern:
137
- ```python
138
- # CORRECT APPROACH - Read, modify in memory, write as one operation
139
- with open(file_path, 'r') as f:
140
- content = f.read() # Read the entire file
141
-
142
- # Make modifications to the content in memory
143
- modified_content = content.replace('old_text', 'new_text')
144
- # OR use regex if needed
145
- import re
146
- modified_content = re.sub(r'pattern', 'replacement', content)
147
-
148
- # Write back the entire file at once
149
- with open(file_path, 'w') as f:
150
- f.write(modified_content) # Write the entire file
151
-
152
- # Verify changes were made
153
- with open(file_path, 'r') as f:
154
- verification = f.read()
155
- print(f"Verification: {'new_text' in verification}")
156
- ```
157
-
158
-AVOID these error-prone approaches:
159
-
160
-❌ Line-by-line reading and writing
161
-❌ Multiple separate f.write() calls
162
-❌ Complex string manipulation without testing
163
-
164
-
165
-For Python files specifically, preserve indentation:
166
-
167
-Use dedicated functions for Python code modification
168
-Be extremely careful with regex replacements
169
-
170
-### CODE EDITING (PYTHON)
136
+1. **RECOMMENDED METHOD (Terminal Heredoc):**
137
+ * Use the `terminal` runtime (session 0) with `cat > /path/to/file << 'EOF' ... EOF`.
138
+ * This is generally preferred for reliability with multi-line content and avoids Python environment issues.
139
+ * **Formatting:** Ensure `\n` for newlines in your JSON `code` string and that the final `EOF` is on its own line.
140
+ * **Verification:** ALWAYS verify the write immediately using `cat /path/to/file` in a subsequent `terminal` call.
141
+ * **Troubleshooting Hangs:** If this command hangs (stuck on a `>` prompt and times out), it indicates the content or `EOF` marker wasn't transmitted correctly. Review your `code` string's formatting and escaping. If it repeatedly hangs, use the Python Fallback.
142
+ ```json
143
+ {
144
+ "thoughts": ["Writing a multi-line file using terminal heredoc"],
145
+ "tool_name": "code_execution_tool",
146
+ "tool_args": {
147
+ "runtime": "terminal",
148
+ "session": 0,
149
+ "code": "cat > path/to/my_script.py << 'EOF'\n# Start of script\nimport os\n\ndef main():\n print(f"Hello from {os.getcwd()}" )\n\nif __name__ == "__main__":\n main()\nEOF"
150
+ }
151
+ }
152
+ ```
153
+ ```json
154
+ {
155
+ "thoughts": ["Verifying the file write"],
156
+ "tool_name": "code_execution_tool",
157
+ "tool_args": {
158
+ "runtime": "terminal",
159
+ "session": 0,
160
+ "code": "cat path/to/my_script.py"
161
+ }
162
+ }
163
+ ```
164
+
165
+2. **PYTHON FALLBACK METHOD (If Terminal Heredoc Hangs):**
166
+ * Use this **only if the terminal `cat > EOF` method hangs repeatedly.**
167
+ * Use `runtime: python` (session 0) with `with open(...) f.write(...)`.
168
+ * Ensure you write the *entire* file content as a single multi-line string.
169
+ ```json
170
+ {
171
+ "thoughts": ["Terminal heredoc hung, using Python fallback to write file"],
172
+ "tool_name": "code_execution_tool",
173
+ "tool_args": {
174
+ "runtime": "python",
175
+ "session": 0,
176
+ "code": "file_path = 'path/to/my_script.py'\ncontent = \"\"\"# Start of script\nimport os\n\ndef main():\n print(f\"Hello from {os.getcwd()}\" )\n\nif __name__ == \"__main__\":\n main()\"\"\"\nwith open(file_path, 'w') as f:\n f.write(content)\nprint(f\"File {file_path} written via Python.\")"
177
+ }
178
+ }
179
+ ```
180
+
181
+**Overall Strategy:**
182
+* ALWAYS read necessary context first (e.g., `cat <file>`).
183
+* Construct the full, new file content in memory.
184
+* Attempt to write using the **Terminal Heredoc** method.
185
+* **Verify** the write.
186
+* If the Terminal Heredoc method hangs, use the **Python Fallback** method.
187
+* Verify again.
188
+* **AVOID** naive string/line replacements or partial edits for code/structured files.
189
+
190
+### CODE EDITING (PYTHON SPECIFIC)
191
- Avoid naive string or line replacements for code edits, especially in Python, as this can break indentation and structure.
192
- Read the file to identify the exact issues. After reviewing the content, implement the necessary fixes to ensure proper syntax throughout the file.
193
- Prefer reading the whole file, editing in memory, and writing back as a single multi-line string for reliability.
python/tools/team_agent.py
+28
-16
@@ -647,43 +647,55 @@ PROJECT CREATION PATTERN:
647
4. Run code in separate sessions from creation
648
5. ALWAYS install packages AND run scripts with terminal runtime to maintain environment consistency
649
650
-FILE EDITING STRATEGIES (Use Terminal First):
650
+FILE EDITING STRATEGIES (Use Terminal First for Writes):
651
652
Reading Files:
653
-- Use `cat /path/to/file` in the terminal runtime.
653
+- Use `cat /path/to/file` in the `terminal` runtime.
654
655
-Writing/Overwriting Files (Preferred Method for Reliability):
656
-- Use `cat > /path/to/file << 'EOF' ... EOF` in the terminal runtime. This is the MOST RELIABLE way to write or overwrite entire files, especially multi-line content or code.
655
+Writing/Overwriting Files (RECOMMENDED METHOD):
656
+- Use `cat > /path/to/file << 'EOF' ... EOF` in the **terminal** runtime (session 0). This is generally the most reliable way to write or overwrite entire files, especially multi-line content or code, avoiding Python environment issues.
657
+- **Formatting:** Ensure correct JSON escaping (`\n` for newlines) and that the final `EOF` is on its own line.
658
```json
659
{{
659
- "thoughts": ["Overwriting file with new content using heredoc"],
660
+ "thoughts": ["Overwriting file with new content using terminal heredoc"],
661
"tool_name": "code_execution_tool",
662
"tool_args": {{
663
"runtime": "terminal",
663
- "session": 0, // Use session 0 for file ops
664
- "code": "cat > /path/to/your/file.py << 'EOF'\\n# Your full new file content here\\nprint(\\'Hello Overwritten World!\\')\\nEOF"
664
+ "session": 0,
665
+ "code": "cat > /path/to/your/file.py << 'EOF'\n# Your full new file content here\nprint(\'Hello Overwritten World!\')\nEOF"
666
}}
667
}}
668
```
669
+- **Verification:** ALWAYS verify the write immediately using `cat /path/to/file` in a subsequent `terminal` call.
670
+- **Troubleshooting:** If this command hangs (shows a `>` prompt and times out), it likely means the multi-line content or the final `EOF` was not transmitted correctly. Double-check formatting and escaping. If it hangs repeatedly, use the Python Fallback method.
671
669
-Creating Empty Files or Simple Overwrites (Less Reliable for complex content):
670
-- `echo "single line" > /path/to/file` or `touch /path/to/file`
672
+Creating Empty Files or Simple Overwrites (Use with Caution):
673
+- `echo "single line" > /path/to/file` or `touch /path/to/file` are acceptable for very simple cases but less reliable for complex content.
674
672
-Python Fallback (If Terminal Methods Fail Repeatedly):
673
-- ONLY if terminal methods fail, use the `python` runtime with file I/O.
675
+Python Fallback (Use if Terminal `cat > EOF` Hangs):
676
+- Use this method **ONLY if the terminal `cat > EOF` method hangs repeatedly** (stuck on `>` prompt).
677
+- Use the `python` runtime (session 0) with standard file I/O.
678
```json
679
{{
676
- "thoughts": ["Terminal file write failed, falling back to Python file I/O"],
680
+ "thoughts": ["Terminal file write failed/hung, falling back to Python file I/O"],
681
"tool_name": "code_execution_tool",
682
"tool_args": {{
679
- "runtime": "python", // Python runtime specifically for this fallback
680
- "session": 0, // Still use session 0
681
- "code": "with open('/path/to/your/file.py', 'w') as f:\\n f.write(\\'\\'\\'# Your full new file content here\\nprint(\\\\\\'Hello Python Fallback!\\\\\\')\\n\\'\\'\\')"
683
+ "runtime": "python",
684
+ "session": 0,
685
+ "code": "with open('/path/to/your/file.py', 'w') as f:\n f.write(\'\'\'# Your full new file content here\nprint(\\\'Hello Python Fallback!\\\')\n\'\'\')\nprint('File written via Python.')"
686
}}
687
}}
688
```
689
686
-*NEVER* use naive string/line replacements or partial edits, especially for code or structured files. Always read the necessary context, modify the content appropriately, and write back the *entire* corrected content using the `cat > ... << EOF` method or the Python fallback.
690
+**Overall Edit Strategy:**
691
+1. Read the necessary context (`cat <file>`).
692
+2. Construct the *entire* new file content in memory.
693
+3. Write the *entire* new content using the **Terminal Heredoc** method first.
694
+4. **Verify** the write (`cat <file>`).
695
+5. If the terminal method **hangs** (stuck on `>`), retry using the **Python Fallback** method.
696
+6. Verify again.
697
+
698
+*NEVER* use naive string/line replacements or partial edits, especially for code or structured files.
699
700
AVAILABLE TOOLS:
701
- knowledge_tool: For research and information gathering