dsh-winrm 0.3.1 → 0.4.1

package/lib/index.js

@@ -322,6 +322,243 @@ function psWriteChunk(p, b64, append) {
 		""
 	].join("\r\n");
 }
+/**
+* JSON: one bounded, line-numbered window of a remote TEXT file.
+*
+* Decodes UTF-8 (with or without BOM), UTF-16LE and UTF-16BE by BOM, and
+* rejects invalid UTF-8 instead of returning mojibake — a binary file fails
+* loudly rather than as unreadable text. Lines are numbered from 1 over the
+* whole file, `offset` selects the first returned line, and the window stops
+* early once the joined text would exceed `maxBytes` (reported as
+* `truncated`, so the caller knows more lines remain). A line longer than
+* `maxLineLength` is cut to `maxLineLength + 1` code units here; the Node half
+* appends the truncation note.
+*
+* A missing path or a directory emits `{"exists":false}`; anything the reader
+* rejects emits `{"error":…}`. Both keep the exit code at 0 so the caller
+* always receives parseable JSON rather than a PowerShell error record.
+* @param p - remote path.
+* @param offset - 1-based first line to return.
+* @param limit - maximum number of lines to return.
+* @param maxLineLength - maximum characters kept per line.
+* @param maxBytes - maximum UTF-8 bytes of joined line text.
+* @returns the PowerShell fragment.
+*/
+function psReadTextWindow(p, offset, limit, maxLineLength, maxBytes) {
+	return [
+		"$__p = " + sq(p),
+		"$__err = $null",
+		"$__json = $null",
+		"try {",
+		"  $__i = Get-Item -LiteralPath $__p -ErrorAction SilentlyContinue",
+		"  if ($null -eq $__i -or $__i.PSIsContainer) {",
+		"    $__json = [pscustomobject]@{ exists = $false } | ConvertTo-Json -Compress",
+		"  } else {",
+		"    $__fs = [System.IO.File]::OpenRead($__p)",
+		"    try {",
+		"      $__b0 = New-Object byte[] 3",
+		"      $__n0 = $__fs.Read($__b0, 0, 3)",
+		"      $__fs.Position = 0",
+		"      $__enc = 'utf8'",
+		"      $__coding = New-Object System.Text.UTF8Encoding($false, $true)",
+		"      if ($__n0 -ge 2 -and $__b0[0] -eq 255 -and $__b0[1] -eq 254) {",
+		"        $__enc = 'utf16le'",
+		"        $__coding = [System.Text.Encoding]::Unicode",
+		"      } elseif ($__n0 -ge 2 -and $__b0[0] -eq 254 -and $__b0[1] -eq 255) {",
+		"        $__enc = 'utf16be'",
+		"        $__coding = [System.Text.Encoding]::BigEndianUnicode",
+		"      } elseif ($__n0 -ge 3 -and $__b0[0] -eq 239 -and $__b0[1] -eq 187 -and $__b0[2] -eq 191) {",
+		"        $__enc = 'utf8bom'",
+		"      }",
+		"      $__r = New-Object System.IO.StreamReader($__fs, $__coding, $true)",
+		"      try {",
+		"        $__total = 0",
+		"        $__sel = New-Object System.Collections.ArrayList",
+		"        $__used = 0",
+		"        $__cut = $false",
+		"        $__bytes = $false",
+		"        while ($null -ne ($__line = $__r.ReadLine())) {",
+		"          $__total++",
+		"          if ($__cut) { continue }",
+		"          if ($__total -lt " + String(offset) + ") { continue }",
+		"          if ($__sel.Count -ge " + String(limit) + ") { $__cut = $true; continue }",
+		"          $__t = $__line",
+		"          if ($__t.Length -gt " + String(maxLineLength + 1) + ") { $__t = $__t.Substring(0, " + String(maxLineLength + 1) + ") }",
+		"          $__b = [System.Text.Encoding]::UTF8.GetByteCount($__t)",
+		"          if ($__sel.Count -gt 0) { $__b++ }",
+		"          if ($__used + $__b -gt " + String(maxBytes) + ") { $__cut = $true; $__bytes = $true; continue }",
+		"          $__used += $__b",
+		"          [void]$__sel.Add($__t)",
+		"        }",
+		"      } finally { $__r.Dispose() }",
+		"    } finally { $__fs.Dispose() }",
+		"    $__json = [pscustomobject]@{",
+		"      exists = $true",
+		"      size = [long]$__i.Length",
+		"      encoding = $__enc",
+		"      totalLines = $__total",
+		"      lineCount = $__sel.Count",
+		"      truncated = $__cut",
+		"      truncatedByBytes = $__bytes",
+		"      linesText = (($__sel | ForEach-Object { [string]$_ }) -join \"`n\")",
+		"    } | ConvertTo-Json -Compress -Depth 3",
+		"  }",
+		"} catch { $__err = $_.Exception.GetBaseException().Message }",
+		"if ($null -ne $__err) { [pscustomobject]@{ error = $__err } | ConvertTo-Json -Compress }",
+		"else { $__json }",
+		""
+	].join("\r\n");
+}
+/**
+* JSON: replace `oldB64` with `newB64` (both UTF-8, base64-carried) in a remote
+* text file, preserving its encoding and writing through the same file.
+*
+* The search is ordinal and never pattern-based, so a replacement cannot be
+* reinterpreted as a regular expression. Without `replaceAll` the edit is
+* refused unless the needle appears exactly once, which is what keeps a stale
+* or too-short needle from rewriting the wrong region. The file is read whole,
+* so this is meant for source files and configuration, not for multi-hundred-
+* megabyte logs.
+*
+* Failures (missing file, absent needle, ambiguous needle, undecodable bytes)
+* are reported as `{"error":…}` with exit code 0 so the caller always receives
+* parseable JSON.
+* @param p - remote path.
+* @param oldB64 - base64 of the UTF-8 text to find.
+* @param newB64 - base64 of the UTF-8 text to substitute.
+* @param replaceAll - replace every occurrence instead of requiring exactly one.
+* @param basisMaxBytes - include the before/after text when the original file is
+*   at most this large; `0` omits the basis entirely.
+* @returns the PowerShell fragment.
+*/
+function psEditText(p, oldB64, newB64, replaceAll, basisMaxBytes = 0) {
+	const branch = replaceAll ? [
+		"  $__count = [int](($__text.Length - $__text.Replace($__old, [string]::Empty).Length) / $__old.Length)",
+		"  if ($__count -eq 0) { throw ('oldString was not found in ' + $__p) }",
+		"  $__out = $__text.Replace($__old, $__new)"
+	] : [
+		"  $__at = $__text.IndexOf($__old, [System.StringComparison]::Ordinal)",
+		"  if ($__at -lt 0) { throw ('oldString was not found in ' + $__p) }",
+		"  if ($__text.IndexOf($__old, $__at + 1, [System.StringComparison]::Ordinal) -ge 0) {",
+		"    throw ('oldString appears more than once in ' + $__p + '; pass replaceAll=true or include more surrounding context')",
+		"  }",
+		"  $__out = $__text.Substring(0, $__at) + $__new + $__text.Substring($__at + $__old.Length)",
+		"  $__count = 1"
+	];
+	const basisGuard = basisMaxBytes > 0 ? `[long]$__i.Length -le ${basisMaxBytes}` : "$false";
+	return [
+		"$__p = " + sq(p),
+		"$__err = $null",
+		"$__json = $null",
+		"try {",
+		"  $__i = Get-Item -LiteralPath $__p -ErrorAction SilentlyContinue",
+		"  if ($null -eq $__i -or $__i.PSIsContainer) { throw ('remote file not found: ' + $__p) }",
+		"  $__old = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String(" + sq(oldB64) + "))",
+		"  $__new = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String(" + sq(newB64) + "))",
+		"  if ($__old.Length -eq 0) { throw " + sq("oldString must be a non-empty string") + " }",
+		"  $__fs = [System.IO.File]::OpenRead($__p)",
+		"  try {",
+		"    $__b0 = New-Object byte[] 3",
+		"    $__n0 = $__fs.Read($__b0, 0, 3)",
+		"    $__fs.Position = 0",
+		"    $__enc = 'utf8'",
+		"    $__coding = New-Object System.Text.UTF8Encoding($false, $true)",
+		"    if ($__n0 -ge 2 -and $__b0[0] -eq 255 -and $__b0[1] -eq 254) {",
+		"      $__enc = 'utf16le'",
+		"      $__coding = [System.Text.Encoding]::Unicode",
+		"    } elseif ($__n0 -ge 2 -and $__b0[0] -eq 254 -and $__b0[1] -eq 255) {",
+		"      $__enc = 'utf16be'",
+		"      $__coding = [System.Text.Encoding]::BigEndianUnicode",
+		"    } elseif ($__n0 -ge 3 -and $__b0[0] -eq 239 -and $__b0[1] -eq 187 -and $__b0[2] -eq 191) {",
+		"      $__enc = 'utf8bom'",
+		"    }",
+		"    $__r = New-Object System.IO.StreamReader($__fs, $__coding, $true)",
+		"    try { $__text = $__r.ReadToEnd() } finally { $__r.Dispose() }",
+		"  } finally { $__fs.Dispose() }",
+		...branch,
+		"  if ($__enc -eq \"utf8bom\") { [System.IO.File]::WriteAllText($__p, $__out, (New-Object System.Text.UTF8Encoding($true))) }",
+		"  elseif ($__enc -eq \"utf16le\") { [System.IO.File]::WriteAllText($__p, $__out, [System.Text.Encoding]::Unicode) }",
+		"  elseif ($__enc -eq \"utf16be\") { [System.IO.File]::WriteAllText($__p, $__out, [System.Text.Encoding]::BigEndianUnicode) }",
+		"  else { [System.IO.File]::WriteAllText($__p, $__out, (New-Object System.Text.UTF8Encoding($false))) }",
+		"  $__basis = $null",
+		"  if (" + basisGuard + ") {",
+		"    $__basis = [pscustomobject]@{",
+		"      before = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($__text))",
+		"      after = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($__out))",
+		"    }",
+		"  }",
+		"  $__json = [pscustomobject]@{",
+		"    path = $__p",
+		"    encoding = $__enc",
+		"    replacements = $__count",
+		"    size = [long](Get-Item -LiteralPath $__p).Length",
+		"    basis = $__basis",
+		"  } | ConvertTo-Json -Compress -Depth 3",
+		"} catch { $__err = $_.Exception.GetBaseException().Message }",
+		"if ($null -ne $__err) { [pscustomobject]@{ error = $__err } | ConvertTo-Json -Compress }",
+		"else { $__json }",
+		""
+	].join("\r\n");
+}
+/**
+* JSON: the whole remote text file as base64, or a refusal when it is missing
+* or larger than `maxBytes`.
+*
+* The write tool needs the previous text to project a diff card, and the line
+* window reader cannot serve that: it numbers lines and caps each one, so a
+* long line would silently truncate inside the diff basis. The BOM detection
+* repeats {@link psEditText}'s on purpose — both must decode identically, and a
+* shared emitter would hide that requirement behind a helper neither could be
+* reviewed against.
+*
+* Failures are reported as `{"error":…}` with exit code 0, so the caller always
+* receives parseable JSON.
+* @param p - remote path.
+* @param maxBytes - largest file whose text is returned.
+* @returns the PowerShell fragment.
+*/
+function psReadTextBasis(p, maxBytes) {
+	return [
+		"$__p = " + sq(p),
+		"$__err = $null",
+		"$__json = $null",
+		"try {",
+		"  $__i = Get-Item -LiteralPath $__p -ErrorAction SilentlyContinue",
+		"  if ($null -eq $__i -or $__i.PSIsContainer) { throw ('remote file not found: ' + $__p) }",
+		`  if ([long]$__i.Length -gt ${maxBytes}) {`,
+		"    $__json = [pscustomobject]@{ tooLarge = $true; encoding = $null; text = $null } | ConvertTo-Json -Compress",
+		"  } else {",
+		"    $__fs = [System.IO.File]::OpenRead($__p)",
+		"    try {",
+		"      $__b0 = New-Object byte[] 3",
+		"      $__n0 = $__fs.Read($__b0, 0, 3)",
+		"      $__fs.Position = 0",
+		"      $__enc = 'utf8'",
+		"      $__coding = New-Object System.Text.UTF8Encoding($false, $true)",
+		"      if ($__n0 -ge 2 -and $__b0[0] -eq 255 -and $__b0[1] -eq 254) {",
+		"        $__enc = 'utf16le'",
+		"        $__coding = [System.Text.Encoding]::Unicode",
+		"      } elseif ($__n0 -ge 2 -and $__b0[0] -eq 254 -and $__b0[1] -eq 255) {",
+		"        $__enc = 'utf16be'",
+		"        $__coding = [System.Text.Encoding]::BigEndianUnicode",
+		"      } elseif ($__n0 -ge 3 -and $__b0[0] -eq 239 -and $__b0[1] -eq 187 -and $__b0[2] -eq 191) {",
+		"        $__enc = 'utf8bom'",
+		"      }",
+		"      $__r = New-Object System.IO.StreamReader($__fs, $__coding, $true)",
+		"      try { $__text = $__r.ReadToEnd() } finally { $__r.Dispose() }",
+		"    } finally { $__fs.Dispose() }",
+		"    $__json = [pscustomobject]@{",
+		"      tooLarge = $false",
+		"      encoding = $__enc",
+		"      text = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($__text))",
+		"    } | ConvertTo-Json -Compress -Depth 3",
+		"  }",
+		"} catch { $__err = $_.Exception.GetBaseException().Message }",
+		"if ($null -ne $__err) { [pscustomobject]@{ error = $__err } | ConvertTo-Json -Compress }",
+		"else { $__json }",
+		""
+	].join("\r\n");
+}
 /** Magic stamped into the frame header that precedes every stream chunk. */
 const STREAM_FRAME_MAGIC = "DSHZ";
 /** Remote-side buffer used while draining stdin (or inflating a frame) into the file. */
@@ -1070,6 +1307,41 @@ const STREAM_GZIP_MIN_RATIO = .85;
 /** Per-Send HTTP budget; a single slice is small, so this only bounds a stalled connection. */
 const STREAM_SEND_TIMEOUT_MS = 12e4;
 /**
+* How long a streaming transfer may deliver nothing before it is treated as
+* stalled.
+*
+* A wall-clock cap on the whole transfer cannot work here: this transport is
+* latency-bound and measured at ~0.73 MiB/s against a real target, so a 700 MiB
+* file legitimately needs about sixteen minutes and any smaller fixed cap fails
+* a transfer that is making steady progress. What a transfer actually needs
+* bounding against is a *stall* — a range that has stopped producing bytes —
+* which is what this idle window measures.
+*/
+const STREAM_IDLE_TIMEOUT_MS = 18e4;
+/**
+* Floor used only to size the runaway backstop, never as a throughput target.
+* Deliberately pessimistic (64 KiB/s): it must not fail a slow link, only a
+* transfer that is somehow still "busy" hours after it should have finished.
+*/
+const STREAM_MIN_BYTES_PER_SEC = 65536;
+/**
+* Budget for one streaming transfer of `bytes` bytes.
+*
+* The idle window is the effective limit; the hard window exists so a wedged
+* transfer cannot stay alive forever, and it scales with the payload because
+* the payload is what sets the legitimate duration.
+* @param bytes - total bytes the transfer must move.
+* @param idleMs - how long the transfer may go without delivering anything.
+* @returns the idle window and the absolute backstop, both in milliseconds.
+*/
+function transferBudget(bytes, idleMs = STREAM_IDLE_TIMEOUT_MS) {
+	const optimisticMs = Math.ceil(Math.max(0, bytes) / STREAM_MIN_BYTES_PER_SEC) * 1e3;
+	return {
+		idleMs,
+		hardMs: Math.max(idleMs * 4, optimisticMs + idleMs)
+	};
+}
+/**
 * One streaming transfer over a single shell: create → run the receiver →
 * push the receiver script, the header frame and every data frame down stdin →
 * receive the envelope → delete the shell.
@@ -1081,13 +1353,13 @@ const STREAM_SEND_TIMEOUT_MS = 12e4;
 * @param remotePath - destination path on the target.
 * @param data - the file contents to send.
 * @param onProgress - called with cumulative bytes after each frame.
-* @param timeoutMs - whole-transfer budget.
+* @param budget - idle window and absolute backstop for the transfer.
 * @param authMethod - the auth scheme for this attempt.
 * @param sendHttp - the resolved library send function.
 * @returns the number of file bytes the receiver acknowledged writing.
 * @throws WinrmTimedOut when the deadline passes; other errors are transport failures.
 */
-async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMethod, sendHttp) {
+async function streamOnce(conn, remotePath, data, onProgress, budget, authMethod, sendHttp) {
 	const base = baseParams(conn, authMethod);
 	const target = {
 		host: conn.host,
@@ -1099,7 +1371,9 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 		useHttps: conn.useHttps ?? false,
 		rejectUnauthorized: conn.rejectUnauthorized ?? true
 	};
-	const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS;
+	const hardDeadline = Date.now() + budget.hardMs + SETUP_GRACE_MS;
+	let lastProgressAt = Date.now();
+	const stalled = () => Date.now() - lastProgressAt >= budget.idleMs;
 	const state = {
 		shellId: void 0,
 		timedOut: false,
@@ -1128,7 +1402,7 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 		let slice = STREAM_CHUNK_BYTES;
 		let ceiling = STREAM_CHUNK_BYTES;
 		while (offset < total) {
-			if (state.settled || Date.now() >= hardDeadline) throw new WinrmTimedOut();
+			if (state.settled || stalled()) throw new WinrmTimedOut();
 			const take = Math.min(slice, total - offset);
 			const chunk = data.subarray(offset, offset + take);
 			const gz = gzipSync(chunk, { level: 6 });
@@ -1145,6 +1419,7 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 				throw error;
 			}
 			offset += take;
+			lastProgressAt = Date.now();
 			onProgress?.(offset, total);
 			if (slice < ceiling) slice = Math.min(ceiling, slice * 2);
 		}
@@ -1153,15 +1428,15 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 			shellId,
 			commandId
 		};
-		const commandDeadline = Date.now() + timeoutMs;
 		let stdout = "";
 		let stderr = "";
 		for (;;) {
-			if (state.settled || Date.now() >= commandDeadline) throw new WinrmTimedOut();
+			if (state.settled || stalled()) throw new WinrmTimedOut();
 			const chunk = await Command.doReceiveOutputNonBlocking(receive);
 			stdout += chunk.output;
 			stderr += chunk.stderr;
 			if (chunk.isComplete) break;
+			if (chunk.output !== "" || chunk.stderr !== "") lastProgressAt = Date.now();
 		}
 		const parsed = parseEnvelope(stdout);
 		if (parsed === null) throw new Error("streaming upload did not report completion: " + (stripClixml(stderr) || stdout).trim());
@@ -1206,16 +1481,17 @@ async function streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMet
 * @param remotePath - destination path on the target.
 * @param data - the file contents to send.
 * @param onProgress - called with cumulative bytes after each frame.
-* @param timeoutMs - whole-transfer budget.
+* @param idleMs - how long the transfer may go without moving a slice.
 * @returns bytes written, or null when the streaming path is unavailable.
 */
-async function uploadStream(conn, remotePath, data, onProgress, timeoutMs = 6e5) {
+async function uploadStream(conn, remotePath, data, onProgress, idleMs = STREAM_IDLE_TIMEOUT_MS) {
 	const sendHttp = loadSendHttp();
 	if (sendHttp === null) return null;
+	const budget = transferBudget(data.length, idleMs);
 	const candidates = conn.useHttps ? ["basic", "ntlm"] : ["ntlm", "basic"];
 	let lastError;
 	for (const authMethod of candidates) try {
-		return await streamOnce(conn, remotePath, data, onProgress, timeoutMs, authMethod, sendHttp);
+		return await streamOnce(conn, remotePath, data, onProgress, budget, authMethod, sendHttp);
 	} catch (error) {
 		if (error instanceof WinrmTimedOut) throw error;
 		lastError = error;
@@ -1235,12 +1511,12 @@ const DOWNLOAD_RECEIVE_TIMEOUT_MS = 12e4;
 * @param start - first byte offset of this worker's range.
 * @param length - bytes this worker must deliver.
 * @param onData - receives each decompressed piece together with its file offset.
-* @param timeoutMs - budget for the whole range.
+* @param budget - idle window and absolute backstop for this worker's range.
 * @param authMethod - the auth scheme for this attempt.
 * @param sendHttp - the resolved library HTTP function.
 * @returns the number of file bytes this worker delivered.
 */
-async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeoutMs, authMethod, sendHttp) {
+async function downloadWorkerOnce(conn, remotePath, start, length, onData, budget, authMethod, sendHttp) {
 	const base = baseParams(conn, authMethod);
 	const target = {
 		host: conn.host,
@@ -1252,7 +1528,9 @@ async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeo
 		useHttps: conn.useHttps ?? false,
 		rejectUnauthorized: conn.rejectUnauthorized ?? true
 	};
-	const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS;
+	const hardDeadline = Date.now() + budget.hardMs + SETUP_GRACE_MS;
+	let lastDataAt = Date.now();
+	const stalled = () => Date.now() - lastDataAt >= budget.idleMs;
 	const state = {
 		shellId: void 0,
 		timedOut: false,
@@ -1287,7 +1565,7 @@ async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeo
 		let stdoutEnded = false;
 		let exitCode;
 		while (!stdoutEnded) {
-			if (state.settled || Date.now() >= hardDeadline) throw new WinrmTimedOut();
+			if (state.settled || stalled()) throw new WinrmTimedOut();
 			const result = await receiveOutput(target, shellId, commandId, sendHttp, DOWNLOAD_RECEIVE_TIMEOUT_MS);
 			let sawData = false;
 			for (const stream of result.streams) {
@@ -1301,6 +1579,7 @@ async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeo
 					if (stream.end) stdoutEnded = true;
 				} else stderr += stream.data.toString("utf8");
 			}
+			if (sawData) lastDataAt = Date.now();
 			if (inflateError !== void 0) throw inflateError;
 			if (result.exitCode !== void 0) exitCode = result.exitCode;
 			if (!sawData && exitCode !== void 0) break;
@@ -1349,15 +1628,16 @@ async function downloadWorkerOnce(conn, remotePath, start, length, onData, timeo
 * @param remotePath - file to read.
 * @param onData - receives each decompressed piece with its absolute file offset.
 * @param onProgress - receives cumulative bytes delivered and the total size.
-* @param timeoutMs - budget for the whole download.
+* @param idleMs - how long a worker may go without delivering bytes.
 * @returns the number of bytes delivered, or null when streaming is unavailable.
 */
-async function downloadStream(conn, remotePath, onData, onProgress, timeoutMs = 6e5) {
+async function downloadStream(conn, remotePath, onData, onProgress, idleMs = STREAM_IDLE_TIMEOUT_MS) {
 	const sendHttp = loadSendHttp();
 	if (sendHttp === null) return null;
 	const total = await remoteFileSize(conn, remotePath);
 	if (total === null) throw new Error(`remote file not found: ${remotePath}`);
 	if (total === 0) return 0;
+	const budget = transferBudget(total, idleMs);
 	const workers = Math.max(1, Math.min(DOWNLOAD_MAX_WORKERS, Math.ceil(total / DOWNLOAD_MIN_RANGE_BYTES)));
 	const rangeSize = Math.ceil(total / workers);
 	let transferred = 0;
@@ -1381,7 +1661,7 @@ async function downloadStream(conn, remotePath, onData, onProgress, timeoutMs =
 					start,
 					length: Math.min(rangeSize, total - start)
 				});
-				await Promise.all(ranges.map((range) => downloadWorkerOnce(conn, remotePath, range.start, range.length, report, timeoutMs, authMethod, sendHttp)));
+				await Promise.all(ranges.map((range) => downloadWorkerOnce(conn, remotePath, range.start, range.length, report, budget, authMethod, sendHttp)));
 				return transferred;
 			} catch (error) {
 				if (error instanceof WinrmTimedOut) throw error;
@@ -1544,7 +1824,7 @@ async function smbReachable(host) {
 }
 /** Error thrown when SMB was requested or probed and the target is not listening. */
 function smbUnavailable(host) {
-	return /* @__PURE__ */ new Error("SMB is not reachable on " + host + ":445 (the admin share needs TCP 445 open and the Server service running)");
+	return /* @__PURE__ */ new Error("SMB is not reachable on " + host + ":445 (the admin share needs TCP 445 open and the Server service running); retry with channel \"winrm\" to transfer over WinRM instead");
 }
 /**
 * Copy one local file to a remote Windows host over SMB, verifying the
@@ -1663,14 +1943,125 @@ var ConsoleSession = class {
 		this.onExit?.(code, error);
 	}
 };
+/**
+* Largest file whose text may serve as a diff basis. Above this the card shows
+* the path and operation without hunks: fetching and projecting a bigger basis
+* would cost another transfer and a large metadata payload for a summary the
+* user reads at a glance.
+*/
+const DIFF_BASIS_MAX_BYTES = 256 * 1024;
+/** Split text into lines, treating every terminator as a separator. */
+function toLines(text) {
+	return text === "" ? [] : text.split(/\r?\n/);
+}
+/**
+* Compute the hunks between two texts.
+* @param path - remote path stamped on every hunk.
+* @param before - file text before the change.
+* @param after - file text after the change.
+* @returns one hunk per contiguous change in file order; empty when equal.
+*/
+function computeHunkDiffs(path, before, after) {
+	if (before === after) return [];
+	const oldLines = toLines(before);
+	const newLines = toLines(after);
+	let head = 0;
+	while (head < oldLines.length && head < newLines.length && oldLines[head] === newLines[head]) head += 1;
+	let tail = 0;
+	while (tail < oldLines.length - head && tail < newLines.length - head && oldLines[oldLines.length - 1 - tail] === newLines[newLines.length - 1 - tail]) tail += 1;
+	const oldMid = oldLines.slice(head, oldLines.length - tail);
+	const newMid = newLines.slice(head, newLines.length - tail);
+	/** Build one hunk around the changed range `[from, to)` in the middle. */
+	const emit = (from, to) => {
+		const start = Math.max(0, from - 3);
+		const stop = Math.min(oldMid.length, to + 3);
+		return {
+			path,
+			oldText: oldLines.slice(head + start, head + stop).join("\n"),
+			newText: newLines.slice(head + start, head + stop).join("\n")
+		};
+	};
+	if (oldMid.length !== newMid.length) return [{
+		path,
+		oldText: oldLines.slice(Math.max(0, head - 3), oldLines.length - Math.max(0, tail - 3)).join("\n"),
+		newText: newLines.slice(Math.max(0, head - 3), newLines.length - Math.max(0, tail - 3)).join("\n")
+	}];
+	const diffs = [];
+	let index = 0;
+	while (index < oldMid.length) {
+		if (oldMid[index] === newMid[index]) {
+			index += 1;
+			continue;
+		}
+		const from = index;
+		while (index < oldMid.length && oldMid[index] !== newMid[index]) index += 1;
+		diffs.push(emit(from, index));
+	}
+	return diffs;
+}
+/**
+* Compute hunks and drop them when the serialized payload would exceed the cap.
+* @param path - remote path stamped on every hunk.
+* @param before - prior text.
+* @param after - text after the change.
+* @returns the kept hunks; empty when nothing changed or the payload is too big.
+*/
+function boundedHunkDiffs(path, before, after) {
+	const diffs = computeHunkDiffs(path, before, after);
+	if (diffs.length === 0) return diffs;
+	return JSON.stringify(diffs).length > 524288 ? [] : diffs;
+}
 //#endregion
 //#region src/engine.ts
+/** Longest single line the reader returns before cutting it (characters). */
+const READ_MAX_LINE_LENGTH = 2e3;
+/** Lines the reader returns when the caller does not choose a page size. */
+const READ_DEFAULT_LIMIT = 2e3;
+/** Most lines the reader will return in one call. */
+const READ_MAX_LIMIT = 5e3;
+/** Byte budget for one read window; keeps the envelope well under the transport limit. */
+const READ_MAX_BYTES = 512 * 1024;
 /** JSON-safe parse of the envelope output into a typed value. */
 function parseJson(text) {
 	const trimmed = text.trim();
 	if (trimmed === "" || trimmed === "null") return [];
 	return JSON.parse(trimmed);
 }
+/**
+* Parse one JSON object out of an envelope's stdout.
+*
+* The file tools report their own failures inside the JSON (`{"error":…}`)
+* with exit code 0, so an unparseable body means the fragment never ran;
+* returning undefined lets the caller say so instead of throwing a
+* `SyntaxError` with no context.
+* @param text - envelope stdout.
+* @returns the parsed object, or undefined when the body is empty or not JSON.
+*/
+function parseObject(text) {
+	const trimmed = text.trim();
+	if (trimmed === "" || trimmed === "null") return void 0;
+	if (!trimmed.startsWith("{")) return void 0;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return;
+	}
+}
+/** Mark an over-long line the reader cut, so the model knows it is incomplete. */
+function annotateCutLine(text) {
+	return text.length > 2e3 ? `${text.slice(0, READ_MAX_LINE_LENGTH)}… (line truncated to ${READ_MAX_LINE_LENGTH} chars)` : text;
+}
+/** Encode text for a remote write, applying the requested byte-order mark. */
+function encodeText(content, encoding) {
+	const body = Buffer.from(content, "utf8");
+	if (encoding === "utf8bom") return Buffer.concat([Buffer.from([
+		239,
+		187,
+		191
+	]), body]);
+	if (encoding === "utf16le") return Buffer.concat([Buffer.from([255, 254]), Buffer.from(content, "utf16le")]);
+	return body;
+}
 /** A tiny per-alias in-flight limiter so GUI bursts do not pile up sockets. */
 var AliasGate = class {
 	queues = /* @__PURE__ */ new Map();
@@ -1844,6 +2235,119 @@ var WinRmEngine = class {
 			}));
 		});
 	}
+	/**
+	* Read a bounded, line-numbered window of a remote text file.
+	*
+	* One PowerShell round trip: the remote side decodes the file, counts every
+	* line, and returns only the requested window, so a large log costs one
+	* transfer of the window rather than of the file.
+	* @param alias - configured host.
+	* @param remotePath - path on the target.
+	* @param offset - 1-based first line to return.
+	* @param limit - maximum number of lines to return.
+	* @returns the window plus the file's total line count and encoding.
+	*/
+	async readFile(alias, remotePath, offset, limit) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		return this.gate.run(alias, async () => {
+			const result = await runScript(connOf(entry), psReadTextWindow(remotePath, offset, limit, READ_MAX_LINE_LENGTH, READ_MAX_BYTES), { timeoutMs: 12e4 });
+			const payload = parseObject(result.stdout);
+			if (payload === void 0) throw new Error(result.stderr.trim() || result.stdout.trim() || `failed to read '${remotePath}'`);
+			if (payload.error !== void 0) throw new Error(`${remotePath}: ${payload.error} (the reader decodes UTF-8 and UTF-16 with a BOM; a binary file has no line structure to show)`);
+			if (payload.exists !== true) throw new Error(`remote file not found: ${remotePath}`);
+			const totalLines = payload.totalLines ?? 0;
+			const lineCount = payload.lineCount ?? 0;
+			if (payload.truncated !== true && offset > totalLines && totalLines > 0) throw new Error(`offset ${offset} is out of range for '${remotePath}' (${totalLines} lines)`);
+			const texts = lineCount === 0 ? [] : (payload.linesText ?? "").split("\n");
+			return {
+				path: remotePath,
+				offset,
+				lines: texts.map((text, index) => ({
+					number: offset + index,
+					text: annotateCutLine(text)
+				})),
+				totalLines,
+				encoding: payload.encoding ?? "utf8",
+				truncatedLines: texts.filter((text) => text.length > READ_MAX_LINE_LENGTH).length,
+				truncatedByBytes: payload.truncatedByBytes === true
+			};
+		});
+	}
+	/**
+	* Write a whole remote text file, creating parent directories as needed.
+	*
+	* Reuses the transfer transport (single streamed stdin when available, the
+	* 48 KiB chunk path otherwise) so a large write does not pay one shell cycle
+	* per chunk.
+	* @param alias - configured host.
+	* @param remotePath - path on the target; overwritten when it exists.
+	* @param content - UTF-8 text to write.
+	* @param encoding - byte-order mark to emit (`utf8`, `utf8bom`, `utf16le`).
+	* @returns the operation kind, byte count, encoding written, and both texts
+	*   the diff card compares.
+	*/
+	async writeFile(alias, remotePath, content, encoding) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		const data = encodeText(content, encoding);
+		return this.gate.run(alias, async () => {
+			const conn = connOf(entry);
+			const previous = await remoteFileSize(conn, remotePath);
+			let before = null;
+			if (previous !== null && previous <= 262144) {
+				const payload = parseObject((await runScript(conn, psReadTextBasis(remotePath, DIFF_BASIS_MAX_BYTES), { timeoutMs: 6e4 })).stdout);
+				if (payload !== void 0 && payload.error === void 0 && payload.tooLarge !== true && typeof payload.text === "string") before = Buffer.from(payload.text, "base64").toString("utf8");
+			}
+			let bytes = await uploadStream(conn, remotePath, data);
+			if (bytes === null) bytes = await uploadBuffer(conn, remotePath, data);
+			return {
+				path: remotePath,
+				operation: previous === null ? "create" : "update",
+				bytes,
+				encoding,
+				before,
+				after: content
+			};
+		});
+	}
+	/**
+	* Replace `oldString` with `newString` inside a remote text file.
+	*
+	* The replacement is literal, never a pattern, and the file's existing
+	* encoding is preserved. Without `replaceAll` the edit is refused unless the
+	* needle is unique, so a stale needle cannot rewrite the wrong region.
+	* @param alias - configured host.
+	* @param remotePath - path on the target.
+	* @param oldString - exact text to find.
+	* @param newString - text to substitute.
+	* @param replaceAll - replace every occurrence instead of requiring one.
+	* @returns the replacement count, the file's new size, and both texts the
+	*   diff card compares.
+	*/
+	async editFile(alias, remotePath, oldString, newString, replaceAll) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) throw new Error(`alias '${alias}' not found`);
+		if (oldString === "") throw new Error("oldString must be a non-empty string");
+		if (oldString === newString) throw new Error("oldString and newString are identical; nothing to change");
+		const oldB64 = Buffer.from(oldString, "utf8").toString("base64");
+		const newB64 = Buffer.from(newString, "utf8").toString("base64");
+		return this.gate.run(alias, async () => {
+			const result = await runScript(connOf(entry), psEditText(remotePath, oldB64, newB64, replaceAll, DIFF_BASIS_MAX_BYTES), { timeoutMs: 12e4 });
+			const payload = parseObject(result.stdout);
+			if (payload === void 0) throw new Error(result.stderr.trim() || result.stdout.trim() || `failed to edit '${remotePath}'`);
+			if (payload.error !== void 0) throw new Error(payload.error);
+			const basis = payload.basis ?? null;
+			return {
+				path: payload.path ?? remotePath,
+				encoding: payload.encoding ?? "utf8",
+				replacements: payload.replacements ?? 0,
+				size: payload.size ?? 0,
+				before: basis === null ? null : Buffer.from(basis.before ?? "", "base64").toString("utf8"),
+				after: basis === null ? null : Buffer.from(basis.after ?? "", "base64").toString("utf8")
+			};
+		});
+	}
 	/** Upload one local file to a remote path. Defaults to SMB with WinRM fallback. */
 	async upload(alias, localPath, remotePath, onProgress, channel = "auto") {
 		const entry = this.store.find(alias);
@@ -1969,16 +2473,19 @@ var WinRmEngine = class {
 					percent: total > 0 ? Math.round(transferred / total * 1e3) / 10 : 0
 				});
 			};
+			let delivered = 0;
 			try {
 				const conn = connOf(entry);
-				if (await downloadStream(conn, remotePath, put, report) === null) {
+				const streamed = await downloadStream(conn, remotePath, put, report);
+				if (streamed === null) {
 					let offset = 0;
 					await downloadChunks(conn, remotePath, (b64) => {
 						const buffer = Buffer.from(b64, "base64");
 						put(offset, buffer);
 						offset += buffer.length;
 					}, report);
-				}
+					delivered = bytes;
+				} else delivered = streamed;
 				await queue;
 				if (sink === null) sink = await open(localPath, "w", 384);
 				completed = true;
@@ -1990,12 +2497,12 @@ var WinRmEngine = class {
 			onProgress?.({
 				phase: "done",
 				file: remotePath,
-				transferred: bytes,
-				total: bytes,
+				transferred: delivered,
+				total: delivered,
 				percent: 100
 			});
 			return {
-				bytes,
+				bytes: delivered,
 				channel: "winrm"
 			};
 		});
@@ -3195,7 +3702,7 @@ function winrmUploadTool(engine) {
 					"smb",
 					"winrm"
 				],
-				description: "Transfer channel: smb (admin share), winrm (streamed over the WinRS stdin channel), or auto (default, SMB first with WinRM fallback)."
+				description: "Transfer channel: auto (default) uses the SMB admin share when TCP 445 answers and otherwise WinRM; smb fails outright when 445 is closed; winrm always streams over the WinRS stdin channel."
 			}
 		},
 		output: {
@@ -3239,7 +3746,7 @@ function winrmUploadTool(engine) {
 function winrmDownloadTool(engine) {
 	return defineTool({
 		name: "winrm_download",
-		description: "Download a remote FILE from a configured Windows host to a local path on this machine. The bytes come over the SMB admin share when it is reachable, otherwise they are streamed over WinRM as parallel byte ranges (the 48 KiB base64 chunk path is kept only as a fallback). Directory download is not supported — download files individually. Triggers: download file from Windows server, fetch remote log/artifact.",
+		description: "Download a remote FILE from a configured Windows host to a local path on this machine. The bytes come over the SMB admin share when it is reachable, otherwise they are streamed over WinRM as parallel byte ranges (the 48 KiB base64 chunk path is kept only as a fallback). Large files are fine: the WinRM path runs for as long as bytes keep arriving and only fails once a range stalls. Directory download is not supported — download files individually. Triggers: download file from Windows server, fetch remote log/artifact.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -3263,7 +3770,7 @@ function winrmDownloadTool(engine) {
 					"smb",
 					"winrm"
 				],
-				description: "Transfer channel: smb (admin share), winrm (streamed over parallel WinRS ranges), or auto (default, SMB first with WinRM fallback)."
+				description: "Transfer channel: auto (default) uses the SMB admin share when TCP 445 answers and otherwise WinRM; smb fails outright when 445 is closed; winrm always streams over parallel WinRS byte ranges."
 			}
 		},
 		output: {
@@ -3373,6 +3880,368 @@ function winrmClusterTool(engine) {
 		}
 	});
 }
+/** Render a read window in the numbered envelope the local read tool uses. */
+function renderWindow(window) {
+	const lines = window.lines ?? [];
+	const offset = window.offset ?? 1;
+	const total = window.totalLines ?? 0;
+	const last = offset + lines.length - 1;
+	const body = lines.map((line) => `${line.number}: ${line.text}`).join("\n");
+	const encoding = window.encoding !== void 0 && window.encoding !== "utf8" ? `, encoding ${window.encoding}` : "";
+	let footer;
+	if (lines.length === 0) footer = total === 0 ? `(End of file - total 0 lines${encoding})` : `(No lines at offset ${offset}; the file has ${total} lines${encoding}.)`;
+	else if (window.truncatedByBytes === true) footer = `(Showing lines ${offset}-${last} of ${total}${encoding}. The window stopped at the byte budget — continue with offset=${last + 1}.)`;
+	else if (last < total) footer = `(Showing lines ${offset}-${last} of ${total}${encoding}. Continue with offset=${last + 1}.)`;
+	else footer = `(End of file - total ${total} lines${encoding})`;
+	const content = body === "" ? footer : `${body}\n\n${footer}`;
+	return [
+		`<path>${window.path ?? ""}</path>`,
+		"<type>file</type>",
+		"<content>",
+		content,
+		"</content>"
+	].join("\n");
+}
+/** The remote read tool: a line-numbered window of a text file on the target. */
+function winrmReadTool(engine) {
+	return defineTool({
+		name: "winrm_read",
+		description: "Read a text file ON A REMOTE Windows host and return its content line-numbered. The path is on the Windows host, not this machine — use `read` for local files. Decodes UTF-8 (with or without BOM) and UTF-16 with a BOM, and refuses binary files instead of returning mojibake. Page through large files with offset and limit. Triggers: read file on Windows server, inspect remote config/log/script.",
+		parameters: {
+			alias: {
+				type: "string",
+				required: true,
+				description: "Host alias from winrm_list."
+			},
+			remotePath: {
+				type: "string",
+				required: true,
+				description: "Path on the remote host, e.g. C:\\temp\\app.log."
+			},
+			offset: {
+				type: "integer",
+				description: "1-based first line to return. Defaults to 1."
+			},
+			limit: {
+				type: "integer",
+				description: `Maximum lines to return (default ${READ_DEFAULT_LIMIT}, max ${READ_MAX_LIMIT}).`
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					path: { type: "string" },
+					offset: { type: "integer" },
+					lines: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								number: {
+									type: "integer",
+									required: true
+								},
+								text: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					totalLines: { type: "integer" },
+					encoding: { type: "string" },
+					truncatedByBytes: { type: "boolean" },
+					truncatedLines: { type: "integer" },
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => text(value.ok ? renderWindow(value) : `read failed: ${value.error ?? "unknown error"}`),
+			presentationMeta: (args, value) => value.ok ? {
+				card: "winrm-read",
+				path: value.path ?? args.remotePath,
+				offset: value.offset ?? 1,
+				lines: value.lines ?? [],
+				totalLines: value.totalLines ?? 0,
+				encoding: value.encoding ?? "utf8",
+				truncatedByBytes: value.truncatedByBytes === true,
+				truncatedLines: value.truncatedLines ?? 0,
+				error: ""
+			} : {
+				card: "winrm-read",
+				path: args.remotePath,
+				offset: 0,
+				lines: [],
+				totalLines: 0,
+				encoding: "",
+				truncatedByBytes: false,
+				truncatedLines: 0,
+				error: value.error ?? "unknown error"
+			}
+		},
+		async execute(args) {
+			const offset = Math.max(1, Math.trunc(args.offset ?? 1));
+			const limit = Math.min(READ_MAX_LIMIT, Math.max(1, Math.trunc(args.limit ?? 2e3)));
+			try {
+				return {
+					ok: true,
+					...await engine.readFile(args.alias, args.remotePath, offset, limit)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}
+	});
+}
+/** The remote write tool: replace a whole text file on the target. */
+function winrmWriteTool(engine) {
+	return defineTool({
+		name: "winrm_write",
+		description: "Write a text file ON A REMOTE Windows host, creating parent directories and overwriting any existing file. The path is on the Windows host, not this machine — use `write` for local files, and prefer winrm_edit when only part of an existing file changes. Line endings are sent verbatim, so include \\r\\n for a Windows-native file. The encoding is whatever `encoding` asks for — rewriting an existing utf16le or utf8bom file without setting it converts the file to plain UTF-8; `winrm_read` names a non-UTF-8 file in its footer when you need to match one. Triggers: write file on Windows server, create remote script/config, overwrite remote file.",
+		parameters: {
+			alias: {
+				type: "string",
+				required: true,
+				description: "Host alias from winrm_list."
+			},
+			remotePath: {
+				type: "string",
+				required: true,
+				description: "Destination path on the remote host, e.g. C:\\temp\\script.ps1 (parent dirs are created)."
+			},
+			content: {
+				type: "string",
+				required: true,
+				description: "Full file content."
+			},
+			encoding: {
+				type: "string",
+				enum: [
+					"utf8",
+					"utf8bom",
+					"utf16le"
+				],
+				description: "Byte-order mark to emit: utf8 (default, no BOM), utf8bom, or utf16le (PowerShell 5.1 reads a BOM-less script as ANSI, so non-ASCII script text needs a BOM). Does not preserve the existing file's encoding — pass it explicitly when overwriting a UTF-16 or BOM-carrying file."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					path: { type: "string" },
+					operation: {
+						type: "string",
+						enum: ["create", "update"]
+					},
+					bytes: { type: "integer" },
+					encoding: {
+						type: "string",
+						enum: [
+							"utf8",
+							"utf8bom",
+							"utf16le"
+						]
+					},
+					diffs: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								path: {
+									type: "string",
+									required: true
+								},
+								oldText: {
+									type: "string",
+									required: true
+								},
+								newText: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					beyondBasis: { type: "boolean" },
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => text(value.ok ? [
+				`<path>${value.path ?? ""}</path>`,
+				"<type>file</type>",
+				"<content>",
+				`${value.operation === "update" ? "Updated" : "Created"} file (${value.bytes ?? 0} bytes)`,
+				"</content>"
+			].join("\n") : `write failed: ${value.error ?? "unknown error"}`),
+			presentationMeta: (args, value) => value.ok ? {
+				card: "winrm-write",
+				path: value.path ?? args.remotePath,
+				operation: value.operation ?? "update",
+				bytes: value.bytes ?? 0,
+				encoding: value.encoding ?? "utf8",
+				diffs: value.diffs ?? [],
+				beyondBasis: value.beyondBasis === true,
+				error: ""
+			} : {
+				card: "winrm-write",
+				path: args.remotePath,
+				operation: "update",
+				bytes: 0,
+				encoding: "",
+				diffs: [],
+				beyondBasis: false,
+				error: value.error ?? "unknown error"
+			}
+		},
+		async execute(args) {
+			try {
+				const outcome = await engine.writeFile(args.alias, args.remotePath, args.content, args.encoding ?? "utf8");
+				const diffs = outcome.before !== null ? boundedHunkDiffs(outcome.path, outcome.before, outcome.after) : outcome.operation === "create" ? boundedHunkDiffs(outcome.path, "", outcome.after) : [];
+				return {
+					ok: true,
+					path: outcome.path,
+					operation: outcome.operation,
+					bytes: outcome.bytes,
+					encoding: outcome.encoding,
+					diffs,
+					beyondBasis: outcome.operation === "update" && outcome.before === null
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}
+	});
+}
+/** The remote edit tool: replace an exact string inside a file on the target. */
+function winrmEditTool(engine) {
+	return defineTool({
+		name: "winrm_edit",
+		description: "Replace an exact string in a text file ON A REMOTE Windows host, preserving the file encoding. The path is on the Windows host, not this machine — use `edit` for local files. `oldString` must match the file byte for byte, including indentation and line endings, and must be unique unless `replaceAll` is set; read the file with winrm_read first. Triggers: edit file on Windows server, patch remote config, change remote script.",
+		parameters: {
+			alias: {
+				type: "string",
+				required: true,
+				description: "Host alias from winrm_list."
+			},
+			remotePath: {
+				type: "string",
+				required: true,
+				description: "Path on the remote host, e.g. C:\\temp\\app.config."
+			},
+			oldString: {
+				type: "string",
+				required: true,
+				description: "Exact text to replace. Must not be empty."
+			},
+			newString: {
+				type: "string",
+				required: true,
+				description: "Replacement text. Must differ from oldString."
+			},
+			replaceAll: {
+				type: "boolean",
+				description: "Replace every occurrence instead of requiring exactly one. Defaults to false."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					path: { type: "string" },
+					encoding: { type: "string" },
+					replacements: { type: "integer" },
+					size: { type: "integer" },
+					diffs: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								path: {
+									type: "string",
+									required: true
+								},
+								oldText: {
+									type: "string",
+									required: true
+								},
+								newText: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					beyondBasis: { type: "boolean" },
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => text(value.ok ? (value.replacements ?? 0) > 1 ? `The file ${value.path ?? ""} has been updated. All ${value.replacements ?? 0} occurrences were successfully replaced.` : `The file ${value.path ?? ""} has been updated successfully.` : `edit failed: ${value.error ?? "unknown error"}`),
+			presentationMeta: (args, value) => value.ok ? {
+				card: "winrm-edit",
+				path: value.path ?? args.remotePath,
+				replacements: value.replacements ?? 0,
+				size: value.size ?? 0,
+				encoding: value.encoding ?? "utf8",
+				diffs: value.diffs ?? [],
+				beyondBasis: value.beyondBasis === true,
+				error: ""
+			} : {
+				card: "winrm-edit",
+				path: args.remotePath,
+				replacements: 0,
+				size: 0,
+				encoding: "",
+				diffs: [],
+				beyondBasis: false,
+				error: value.error ?? "unknown error"
+			}
+		},
+		async execute(args) {
+			try {
+				const outcome = await engine.editFile(args.alias, args.remotePath, args.oldString, args.newString, args.replaceAll ?? false);
+				const diffs = outcome.before !== null && outcome.after !== null ? boundedHunkDiffs(outcome.path, outcome.before, outcome.after) : [];
+				return {
+					ok: true,
+					path: outcome.path,
+					encoding: outcome.encoding,
+					replacements: outcome.replacements,
+					size: outcome.size,
+					diffs,
+					beyondBasis: outcome.before === null
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}
+	});
+}
 //#endregion
 //#region src/mount-once.ts
 /**
@@ -3435,7 +4304,7 @@ const DEFAULT_ENABLED = true;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 151;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const WINRM_GUIDANCE = "本机已安装 dsh-winrm 插件（DSH 远程 Windows 运维，WinRM/PowerShell Remoting）：侧边栏「Windows」入口；仿照 dsh-ssh 插件开发。能力：主机配置存 ~/.dsh/dsh-winrm.json（GUI 配置后 agent 方可使用）；winrm_list 列出主机、winrm_exec 执行 PowerShell 命令（UTF-8 信封，中文不乱码）、winrm_service 服务管理（start/stop/restart/启动类型）、winrm_process 进程管理（list/kill）、winrm_upload/winrm_download 文件传输（SMB 管理共享可达时优先，否则走 WinRM 流式传输，无 SMB 依赖，大文件经 SHA256 校验）、winrm_cluster 集群并发执行；Web 控制台走 WebSocket。认证：通过原生 Node.js WinRM 客户端（winrm-client）的 NTLM/Negotiate 与 Basic 实现，兼容本地账户与域账户；传输支持 http(5985)/https(5986)。前提：目标机需启用 WinRM（scripts/enable-winrm.ps1），本机无需 Python —— WinRM 走纯 Node 依赖。HTTP 仅建议受信内网使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出可能含敏感信息；传输/执行消耗真实远程资源，先确认再操作。用户提到「Windows 服务器 / WinRM / PowerShell 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。";
+const WINRM_GUIDANCE = "本机已安装 dsh-winrm 插件（DSH 远程 Windows 运维，WinRM/PowerShell Remoting）：侧边栏「Windows」入口；仿照 dsh-ssh 插件开发。能力：主机配置存 ~/.dsh/dsh-winrm.json（GUI 配置后 agent 方可使用）；winrm_list 列出主机、winrm_exec 执行 PowerShell 命令（UTF-8 信封，中文不乱码）、winrm_service 服务管理（start/stop/restart/启动类型）、winrm_process 进程管理（list/kill）、winrm_read/winrm_write/winrm_edit 远程文本文件读写（按行分页、编码感知、精确串替换，作用于远端主机而非本机，本机文件仍用 read/write/edit）、winrm_upload/winrm_download 文件传输（channel=auto 时若目标 445 可达走 SMB 管理共享，否则走 WinRM 流式传输；channel=smb 在 445 关闭时直接报错、需改用 winrm；大文件可下载，流式通道按字节持续推进、仅在字节断流时才判超时、完成后经 SHA256 校验）、winrm_cluster 集群并发执行；Web 控制台走 WebSocket。认证：通过原生 Node.js WinRM 客户端（winrm-client）的 NTLM/Negotiate 与 Basic 实现，兼容本地账户与域账户；传输支持 http(5985)/https(5986)。前提：目标机需启用 WinRM（scripts/enable-winrm.ps1），本机无需 Python —— WinRM 走纯 Node 依赖。HTTP 仅建议受信内网使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出可能含敏感信息；传输/执行消耗真实远程资源，先确认再操作。用户提到「Windows 服务器 / WinRM / PowerShell 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。";
 /**
 * Mount the WinRM engine, routes, tools, and announcement.
 * @param ctx - host plugin context carrying webServer/tools/systemPrompt.
@@ -3458,6 +4327,9 @@ function applyImpl(ctx, config) {
 		winrmExecTool(engine),
 		winrmServiceTool(engine),
 		winrmProcessTool(engine),
+		winrmReadTool(engine),
+		winrmWriteTool(engine),
+		winrmEditTool(engine),
 		winrmUploadTool(engine),
 		winrmDownloadTool(engine),
 		winrmClusterTool(engine)