@agi-cli/sdk 0.1.80 → 0.1.82

package/src/core/src/tools/builtin/patch.txt

@@ -1,4 +1,11 @@
-Apply a patch to modify one or more files using the enveloped patch format.
+Apply a patch to modify one or more files. The tool accepts the **enveloped patch format** (preferred) and will also auto-convert standard unified diffs (`--- / +++`) if you provide one.
+
+**Quick checklist before you call the tool:**
+- Finished patch must include both `*** Begin Patch` and `*** End Patch`
+- Each change needs a directive (`*** Add File`, `*** Update File`, `*** Delete File`)
+- Include real context lines (prefixed with space) around your changes
+- Keep paths relative to the project root
+- **Use multiple `@@` hunks for multiple edits to the same file - do NOT make separate tool calls**
 
 **RECOMMENDED: Use apply_patch for targeted file edits to avoid rewriting entire files and wasting tokens.**
 
@@ -15,9 +22,47 @@ Use `apply_patch` only when:
 Never rely on memory or previous reads. Even with fuzzy matching enabled (tolerates tabs vs spaces),
 If the file content has changed significantly since you last read it, the patch may still fail.
 
+**ALLOW REJECTS**: If you are applying a patch that might include stale hunks, set `allowRejects: true`.
+The tool will apply the hunks it can and skip the rest, returning the skipped hunks with reasons.
+
+**ALREADY APPLIED?**: If the removal lines are already gone or the additions are already present, the tool will treat the hunk as applied and move on—no need to resend the same change.
+
 **Alternative: Use the `edit` tool if you need fuzzy matching or structured operations.**
 
-## Patch Format
+## ⚠️ CRITICAL: Multiple Edits to Same File
+
+**DO NOT make separate `apply_patch` calls for the same file!**
+
+Instead, use multiple `@@` hunks in a single patch:
+
+```
+*** Begin Patch
+*** Update File: src/app.ts
+@@ first change - line 10
+ function init() {
+-  const port = 3000;
++  const port = 8080;
+   return port;
+ }
+@@ second change - line 25
+ function start() {
+-  console.log("Starting...");
++  console.log("Server starting...");
+   init();
+ }
+@@ third change - line 40
+ function cleanup() {
+-  // TODO
++  console.log("Cleaning up...");
+ }
+*** End Patch
+```
+
+**This makes ONE tool call instead of three, saving tokens and reducing latency.**
+
+## Patch Formats
+
+### Preferred: Enveloped Patch
 
 All patches must be wrapped in markers and use explicit file directives:
 
@@ -33,6 +78,21 @@ All patches must be wrapped in markers and use explicit file directives:
 *** End Patch
 ```
 
+### Also Supported: Standard Unified Diff
+
+You can paste a regular `git diff` style patch:
+
+```
+diff --git a/src/app.ts b/src/app.ts
+--- a/src/app.ts
++++ b/src/app.ts
+@@
+-const PORT = 3000;
++const PORT = 8080;
+```
+
+The tool will convert it automatically, but the enveloped format is still recommended because it is more explicit and easier to control.
+
 ## File Operations
 
 ### Add a new file:
@@ -60,7 +120,7 @@ All patches must be wrapped in markers and use explicit file directives:
 ```
 *** Begin Patch
 *** Update File: src/app.ts
-@@ function main() - locates the change position
+@@ function main()
  function main() {
 -  console.log("old");
 +  console.log("new");
@@ -68,9 +128,33 @@ All patches must be wrapped in markers and use explicit file directives:
 *** End Patch
 ```
 
-**IMPORTANT**: The `@@ context line` is a hint for finding the location - it's NOT a line from the file.
-It should describe what to look for (e.g., `@@ inside main function` or `@@ config section`).
-The actual context lines (with leading space) come AFTER the `@@` line.
+**IMPORTANT**: 
+- The `@@` line is an OPTIONAL hint to help locate the change - it's a comment, not parsed as context
+- REQUIRED: Actual context lines (starting with space ` `) that match the file exactly
+- The context lines with space prefix are what the tool uses to find the location
+- The `@@` line just helps humans/AI understand what section you're editing
+
+
+### Update multiple locations in the same file:
+```
+*** Begin Patch
+*** Update File: src/app.ts
+@@ first section - near line 10
+ function init() {
+-  const port = 3000;
++  const port = 8080;
+   return port;
+ }
+@@ second section - near line 25
+ function start() {
+-  console.log("Starting...");
++  console.log("Server starting...");
+   init();
+ }
+*** End Patch
+```
+
+**IMPORTANT**: Use separate `@@` headers for each non-consecutive change location. This allows multiple edits to the same file in one patch, saving tokens and reducing tool calls.
 
 ### Delete a file:
 ```
@@ -96,16 +180,22 @@ The actual context lines (with leading space) come AFTER the `@@` line.
 - Lines starting with `+` are added
 - Lines starting with `-` are removed  
 - Lines starting with ` ` (space) are context (kept unchanged)
-- Lines starting with `@@` provide context for finding the location
+- Lines starting with `@@` are optional hints/comments (not parsed as context)
 
 ## Common Errors
 
-**"Failed to find expected lines"**: The file content doesn't match your patch. The file may have changed, or you may have mistyped the lines. Solution: Use the `edit` tool instead.
+**"Failed to find expected lines"**: The file content doesn't match your patch. Common causes:
+- Missing context lines (lines with space prefix)
+- Using `@@` line as context instead of real context lines
+- The file content has changed since you read it
+- Whitespace/indentation mismatch
+
+**Solution**: Always read the file immediately before patching and include actual context lines with space prefix.
 
 ## Important Notes
 
 - **Patches are fragile**: Any mismatch in whitespace, indentation, or content will cause failure
 - **Use `edit` for reliability**: The `edit` tool can make targeted changes without requiring exact matches
 - All file paths are relative to the project root
-- The patch format does NOT support standard unified diff format (no `---`/`+++` headers)
-- Always wrap patches with `*** Begin Patch` and `*** End Patch`
+- The enveloped format is the most reliable; unified diffs are converted automatically if provided
+- Always wrap patches with `*** Begin Patch` and `*** End Patch` when you write them manually

package/src/prompts/src/agents/build.txt

@@ -3,3 +3,50 @@ You help with coding and build tasks.
 - Inspect with tools; write with care and small diffs.
 - Keep tool inputs short; avoid long prose inside tool parameters.
 - Stream your answer, then call finish.
+
+## File Editing Best Practices
+
+**Using the `apply_patch` Tool** (Recommended):
+- **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
+- Primary choice for targeted file edits - avoids rewriting entire files
+- Prefer the enveloped format (`*** Begin Patch` ...); standard unified diffs (`---/+++`) are also accepted and auto-converted when provided
+- Only requires the specific lines you want to change
+- Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
+- For multiple changes in one file: use multiple `@@` headers to separate non-consecutive hunks
+- MUST include context lines (space prefix) - the `@@` line is just an optional hint
+- Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
+- The `-` lines in your patch MUST match exactly what's in the file character-for-character
+- If patch fails, it means the file content doesn't match - read it again and retry
+- Set `allowRejects: true` when you expect some hunks might be stale so the tool applies what it can and reports the skipped parts
+- Removal lines that are already gone (or additions already present) are treated as applied automatically—no need to resend them
+- **Best for**: Small, surgical edits to code files (< 50 line changes per file)
+- **Struggles with**: Large restructures (> 50 lines), major section reorganizations
+
+**Patch Format Reminder**:
+```
+*** Update File: path
+@@ optional hint              ← Optional comment/hint (not parsed)
+ actual line from file        ← Context (space prefix) - REQUIRED
+-line to remove               ← Remove this line
++line to add                  ← Add this line
+ more context                 ← More context (space prefix)
+```
+
+**Using the `edit` Tool** (Alternative):
+- Specify the file path and a list of operations
+- Operations are applied sequentially to the latest file state
+- Operation types: `replace`, `insert-before`, `insert-after`, `delete`
+- Each operation includes: `old` (text to match/find) and `new` (replacement/insertion)
+- When making multiple changes to a file, use ONE `edit` call with multiple ops
+
+**Using the `write` Tool** (Last Resort):
+- Use for creating NEW files
+- Use when replacing >70% of a file's content (almost complete rewrite)
+- NEVER use for targeted edits - it rewrites the entire file
+- Wastes output tokens and risks hallucinating unchanged parts
+
+**Never**:
+- Use `write` for partial file edits (use `apply_patch` or `edit` instead)
+- Make multiple separate `edit` or `apply_patch` calls for the same file (use multiple hunks with @@ headers or multiple ops instead)
+- Assume file content remains unchanged between operations
+- Use `bash` with `sed`/`awk` for programmatic file editing (use `edit` instead)

package/src/prompts/src/providers/anthropic.txt

@@ -74,41 +74,10 @@ When making changes to files, first understand the file's code conventions. Mimi
 - IMPORTANT: DO NOT ADD ***ANY*** COMMENTS unless asked
 
 ## Tool Selection Guidelines
-- For file editing, prefer `apply_patch` for targeted edits to avoid rewriting entire files and wasting tokens
-- When you need to make multiple edits to the same file, combine them in a single `edit` call with multiple ops
 - Use `ripgrep` over `grep` for faster searching across large codebases
 - Always use `glob` first to discover files before reading them, unless you know exact paths
 - Call `progress_update` at each major phase: planning, discovering, preparing, writing, verifying
 
-## File Editing Best Practices
-
-**Using the `apply_patch` Tool** (Recommended):
-- **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
-- Primary choice for targeted file edits - avoids rewriting entire files
-- Only requires the specific lines you want to change
-- Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
-- Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
-- The `-` lines in your patch MUST match exactly what's in the file character-for-character
-- If patch fails, it means the file content doesn't match - read it again and retry
-
-**Using the `edit` Tool** (Alternative):
-- Specify the file path and a list of operations
-- Operations are applied sequentially to the latest file state
-- Operation types: `replace`, `insert-before`, `insert-after`, `delete`
-- Each operation includes: `old` (text to match/find) and `new` (replacement/insertion)
-- When making multiple changes to a file, use ONE `edit` call with multiple ops
-
-**Using the `write` Tool** (Last Resort):
-- Only use when creating new files or completely replacing file content
-- NEVER use for targeted edits - it rewrites the entire file
-- Wastes output tokens and risks hallucinating unchanged parts
-
-**Never**:
-- Use `write` for partial file edits (use `apply_patch` or `edit` instead)
-- Make multiple separate `edit` or `apply_patch` calls for the same file
-- Assume file content remains unchanged between operations
-- Use `bash` with `sed`/`awk` for programmatic file editing (use `edit` instead)
-
 ## Search & Discovery Workflow
 
 **Step 1 - Understand Structure**:

package/src/prompts/src/providers/default.txt

@@ -49,11 +49,28 @@ You have access to a rich set of specialized tools optimized for coding tasks:
 **Using the `apply_patch` Tool** (Recommended):
 - **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
 - Primary choice for targeted file edits - avoids rewriting entire files
+- Preferred format is the enveloped patch (`*** Begin Patch` ...); standard unified diffs (`---/+++`) are also accepted and auto-converted if provided
 - Only requires the specific lines you want to change
 - Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
+- For multiple changes in one file: use multiple `@@` headers to separate non-consecutive hunks
+- MUST include context lines (space prefix) - the `@@` line is just an optional hint
 - Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
 - The `-` lines in your patch MUST match exactly what's in the file character-for-character
 - If patch fails, it means the file content doesn't match - read it again and retry
+- If you suspect parts of the patch might be stale, set `allowRejects: true` so the tool applies what it can and reports the skipped hunks with reasons
+- The tool quietly skips removal lines that are already gone and additions that already exist, so you don't need to resend the same change
+- **Best for**: Small, surgical edits to code files (< 50 line changes per file)
+- **Struggles with**: Large restructures (> 50 lines), major section reorganizations
+
+**Patch Format Reminder**:
+```
+*** Update File: path
+@@ optional hint              ← Optional comment/hint (not parsed)
+ actual line from file        ← Context (space prefix) - REQUIRED
+-line to remove               ← Remove this line
++line to add                  ← Add this line
+ more context                 ← More context (space prefix)
+```
 
 **Using the `edit` Tool** (Alternative):
 - Specify the file path and a list of operations
@@ -63,13 +80,14 @@ You have access to a rich set of specialized tools optimized for coding tasks:
 - When making multiple changes to a file, use ONE `edit` call with multiple ops
 
 **Using the `write` Tool** (Last Resort):
-- Only use when creating new files or completely replacing file content
+- Use for creating NEW files
+- Use when replacing >70% of a file's content (almost complete rewrite)
 - NEVER use for targeted edits - it rewrites the entire file
 - Wastes output tokens and risks hallucinating unchanged parts
 
 **Never**:
 - Use `write` for partial file edits (use `apply_patch` or `edit` instead)
-- Make multiple separate `edit` or `apply_patch` calls for the same file
+- Make multiple separate `edit` or `apply_patch` calls for the same file (use multiple hunks with @@ headers or multiple ops instead)
 - Assume file content remains unchanged between operations
 - Use `bash` with `sed`/`awk` for programmatic file editing (use `edit` instead)
 

package/src/prompts/src/providers/google.txt

@@ -18,43 +18,10 @@ You are opencode, an interactive CLI agent specializing in software engineering
 Your primary tools for coding tasks are:
 - **Discovery**: `glob` (find files), `ripgrep` (search content), `tree` (directory structure)
 - **Reading**: `read` (individual files), `ls` (directory listing)
-- **Editing**: `apply_patch` (recommended - targeted edits), `edit` (alternative - structured ops)
 - **Execution**: `bash` (run commands), `git_*` tools (version control)
 - **Planning**: `update_plan` (create and track task plans)
 - **Progress**: `progress_update` (inform user of current phase)
 
-**Critical**: When you make multiple edits to the same file, combine them in a SINGLE `edit` 
-call with multiple ops. Each separate `edit` operation re-reads the file fresh.
-
-## File Editing Best Practices
-
-**Using the `apply_patch` Tool** (Recommended):
-- **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
-- Primary choice for targeted file edits - avoids rewriting entire files
-- Only requires the specific lines you want to change
-- Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
-- Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
-- The `-` lines in your patch MUST match exactly what's in the file character-for-character
-- If patch fails, it means the file content doesn't match - read it again and retry
-
-**Using the `edit` Tool** (Alternative):
-- Specify the file path and a list of operations
-- Operations are applied sequentially to the latest file state
-- Operation types: `replace`, `insert-before`, `insert-after`, `delete`
-- Each operation includes: `old` (text to match/find) and `new` (replacement/insertion)
-- When making multiple changes to a file, use ONE `edit` call with multiple ops
-
-**Using the `write` Tool** (Last Resort):
-- Only use when creating new files or completely replacing file content
-- NEVER use for targeted edits - it rewrites the entire file
-- Wastes output tokens and risks hallucinating unchanged parts
-
-**Never**:
-- Use `write` for partial file edits (use `apply_patch` or `edit` instead)
-- Make multiple separate `edit` or `apply_patch` calls for the same file
-- Assume file content remains unchanged between operations
-- Use `bash` with `sed`/`awk` for programmatic file editing (use `edit` instead)
-
 ## Search & Discovery Workflow
 
 **Step 1 - Understand Structure**:

package/src/prompts/src/providers/openai.txt

@@ -53,13 +53,6 @@ Before making tool calls, send a brief preamble to the user explaining what you'
 
 Your toolset includes specialized file editing and search tools. Follow these guidelines:
 
-**File Editing**:
-- Prefer `apply_patch` tool for targeted edits - avoids rewriting entire files
-- Use `edit` tool as alternative when you need structured operations
-- NEVER use `write` for partial edits - it rewrites the entire file and wastes tokens
-- When editing the same file multiple times, batch operations in a single `edit` call
-- Each separate `edit` operation re-reads the file, so ops within one call are sequential
-
 **Search & Discovery**:
 - Use `glob` to find files by pattern: `*.ts`, `**/*.tsx`, `src/**/*.{js,ts}`
 - Use `ripgrep` for content search - it's MUCH faster than `grep`
@@ -70,35 +63,6 @@ Your toolset includes specialized file editing and search tools. Follow these gu
 - Keep progress messages short (<= 80 chars) and actionable
 - Use stages: planning, discovering, generating, preparing, writing, verifying
 
-## File Editing Best Practices
-
-**Using the `apply_patch` Tool** (Recommended):
-- **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
-- Primary choice for targeted file edits - avoids rewriting entire files
-- Only requires the specific lines you want to change
-- Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
-- Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
-- The `-` lines in your patch MUST match exactly what's in the file character-for-character
-- If patch fails, it means the file content doesn't match - read it again and retry
-
-**Using the `edit` Tool** (Alternative):
-- Specify the file path and a list of operations
-- Operations are applied sequentially to the latest file state
-- Operation types: `replace`, `insert-before`, `insert-after`, `delete`
-- Each operation includes: `old` (text to match/find) and `new` (replacement/insertion)
-- When making multiple changes to a file, use ONE `edit` call with multiple ops
-
-**Using the `write` Tool** (Last Resort):
-- Only use when creating new files or completely replacing file content
-- NEVER use for targeted edits - it rewrites the entire file
-- Wastes output tokens and risks hallucinating unchanged parts
-
-**Never**:
-- Use `write` for partial file edits (use `apply_patch` or `edit` instead)
-- Make multiple separate `edit` or `apply_patch` calls for the same file
-- Assume file content remains unchanged between operations
-- Use `bash` with `sed`/`awk` for programmatic file editing (use `edit` instead)
-
 ## Search & Discovery Workflow
 
 **Step 1 - Understand Structure**: