// Atomic write pattern: Write to temp → atomic rename → delete temp on failure
const tempFile = `${originalPath}.${crypto.randomBytes(9).toString('hex')}.tmp`; // 72-bit entropy
await fs.writeFile(tempFile, content);           // Write to randomized temp
await fs.rename(tempFile, originalPath);          // Atomic rename (survives crashes)
// If interrupted: temp file orphaned but original intact

// Renames 'oldVar' to 'newVar' across the entire file
{
  "file_path": "./src/index.ts",
  "operation": "rename_identifier",
  "old_name": "oldVar",
  "new_name": "newVar"
}

// Moves 'calculateTotal' from src.ts to utils.ts
{
  "file_path": "./src/operations.ts",
  "operation": "move_function",
  "old_name": "placeholder", // required by schema, ignored for this operation
  "function_name": "calculateTotal",
  "target_path": "./src/utils.ts"
}

// Extracts the provided code block into a function named 'processData'
{
  "file_path": "./src/handler.ts",
  "operation": "extract_function",
  "old_name": "const result = value * 2;\nconsole.log(result);", // raw code to extract
  "new_name": "processData"
}

// Scans file for dead imports and removes them automatically
{
  "file_path": "./src/module.ts",
  "operation": "unused_import_cleanup"
}

// Pattern-based — works regardless of current line number:
line_operations(
  file_name, 
  operation: "insert", 
  insert_after_pattern: "if (width <= 0 || height <= 0)",
  content: "// fix"
)
→ Finds line containing pattern → inserts after it → works correctly even if file changed

// Verification-based — catches drift errors before corruption:
line_operations(
  file_name, 
  operation: "insert", 
  target_line: 84, 
  content: "// fix",
  verify_before_insert: "return;" // Content expected at line 84
)
→ Checks if line 84 contains "return;" → If no → BLOCKS with error + context shown (±3 lines)

pending → in_progress → done (terminal)
any     → blocked      ← blocked → pending (retry)

// 1. Create plan with goal and steps
create_plan({
  goal: "Refactor authentication module",
  steps: [
    "Read current auth.ts file",
    "Identify refactoring opportunities",
    "Implement changes to separate concerns",
    "Run tests to verify functionality"
  ]
})

// 2. Track progress as you work
update_plan_step({ planId: "...", index: 0, status: "done" })
update_plan_step({ planId: "...", index: 1, status: "in_progress" })

// 3. Check current state
get_plan() // Returns full plan with progress metrics

// 4. Handle blockers if needed
update_plan_step({ planId: "...", index: 2, status: "blocked", note: "Need API documentation for new auth flow" })

determineConfidence(operationType: 'extraction'|'inference'|'execution'|'search', success: boolean, fallbackUsed?: boolean): Confidence;
createToolResult<T>(data: T, confidence: Confidence, options?: {provenance?: string; note?: string}): { success: true; data: T & ToolResultMetadata };
createErrorResult(message: string, provenance?: string): { success: false; error: string; data: ToolResultMetadata };

{
  imagePath: string;        // Path to image file or attached filename
  prompt?: string;          // Optional analysis prompt (e.g., "Describe this image in detail", "What text is visible?")
}

// Atomic write pattern: Write to temp → atomic rename → delete temp on failure
const tempFile = `${originalPath}.${crypto.randomBytes(9).toString('hex')}.tmp`; // 72-bit entropy
await fs.writeFile(tempFile, content);           // Write to randomized temp
await fs.rename(tempFile, originalPath);          // Atomic rename (survives crashes)
// If interrupted: temp file orphaned but original intact

// Renames 'oldVar' to 'newVar' across the entire file
{
  "file_path": "./src/index.ts",
  "operation": "rename_identifier",
  "old_name": "oldVar",
  "new_name": "newVar"
}

// Moves 'calculateTotal' from src.ts to utils.ts
{
  "file_path": "./src/operations.ts",
  "operation": "move_function",
  "old_name": "placeholder", // required by schema, ignored for this operation
  "function_name": "calculateTotal",
  "target_path": "./src/utils.ts"
}

// Extracts the provided code block into a function named 'processData'
{
  "file_path": "./src/handler.ts",
  "operation": "extract_function",
  "old_name": "const result = value * 2;\nconsole.log(result);", // raw code to extract
  "new_name": "processData"
}

// Scans file for dead imports and removes them automatically
{
  "file_path": "./src/module.ts",
  "operation": "unused_import_cleanup"
}

// Pattern-based — works regardless of current line number:
line_operations(
  file_name, 
  operation: "insert", 
  insert_after_pattern: "if (width <= 0 || height <= 0)",
  content: "// fix"
)
→ Finds line containing pattern → inserts after it → works correctly even if file changed

// Verification-based — catches drift errors before corruption:
line_operations(
  file_name, 
  operation: "insert", 
  target_line: 84, 
  content: "// fix",
  verify_before_insert: "return;" // Content expected at line 84
)
→ Checks if line 84 contains "return;" → If no → BLOCKS with error + context shown (±3 lines)

pending → in_progress → done (terminal)
any     → blocked      ← blocked → pending (retry)

// 1. Create plan with goal and steps
create_plan({
  goal: "Refactor authentication module",
  steps: [
    "Read current auth.ts file",
    "Identify refactoring opportunities",
    "Implement changes to separate concerns",
    "Run tests to verify functionality"
  ]
})

// 2. Track progress as you work
update_plan_step({ planId: "...", index: 0, status: "done" })
update_plan_step({ planId: "...", index: 1, status: "in_progress" })

// 3. Check current state
get_plan() // Returns full plan with progress metrics

// 4. Handle blockers if needed
update_plan_step({ planId: "...", index: 2, status: "blocked", note: "Need API documentation for new auth flow" })

determineConfidence(operationType: 'extraction'|'inference'|'execution'|'search', success: boolean, fallbackUsed?: boolean): Confidence;
createToolResult<T>(data: T, confidence: Confidence, options?: {provenance?: string; note?: string}): { success: true; data: T & ToolResultMetadata };
createErrorResult(message: string, provenance?: string): { success: false; error: string; data: ToolResultMetadata };

{
  imagePath: string;        // Path to image file or attached filename
  prompt?: string;          // Optional analysis prompt (e.g., "Describe this image in detail", "What text is visible?")
}