dsh-winrm 0.3.1 → 0.4.1

package/src/client/tool/cards.tsx

@@ -0,0 +1,335 @@
+/**
+ * Transcript cards for `winrm_read`, `winrm_write` and `winrm_edit`.
+ *
+ * Without these the three tools render as the generic tool row, so the user
+ * reads the same envelope text the model reads. Every call becomes a collapsed
+ * disclosure with a one-line header — file-type icon, verb, remote path — that
+ * expands into a card. The header is drawn from the first dispatch, so settling
+ * only fills in the trailing figure instead of replacing the row: the line the
+ * user watched while it ran is the line they click to open the result.
+ *
+ * Collapsed by default is the harness's own convention for these rows: a long
+ * file would otherwise fill the transcript before the user asked for it.
+ *
+ * The header is `DisclosureRow` and the body is `ReadBlock` / `DiffBlock`, all
+ * from the harness's published `ui-primitives`, so a remote file looks and
+ * behaves exactly like a local one. Open state comes from the `useDisclosure`
+ * hook the Tool layer hands every toolview, which also resets it when the
+ * enclosing turn re-renders.
+ * @module dsh-winrm/src/client/tool/cards
+ */
+import type { ReactNode } from 'react'
+import {
+  DiffBlock, DisclosureRow, FileTypeIcon, ReadBlock,
+  type DiffBlockLabels, type DiffHunk, type ReadBlockLabels,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client'
+import { tt } from '../panel/helpers.ts'
+import { diffCard, readCard, type DiffCard as DiffCardModel, type ReadCard as ReadCardModel } from './card-model.ts'
+import css from './cards.module.css'
+
+/** The Tool view props these cards read. */
+export type WinrmFileCardProps = ToolCallViewProps
+
+/**
+ * Content lines a transcript card shows before the primitive collapses the
+ * middle. Half the primitive's own default (16), because a chat row summarizes
+ * inside a message flow while a dedicated panel is the reading surface. Mirrors
+ * the harness's `CHAT_READ_MAX_LINES` / `CHAT_DIFF_MAX_LINES`.
+ */
+const CHAT_READ_MAX_LINES = 8
+const CHAT_DIFF_MAX_LINES = 9
+
+/** Grammar hint from a remote path's extension; unknown extensions stay plain. */
+const LANG_BY_EXTENSION: Readonly<Record<string, string>> = {
+  bat: 'bat', cmd: 'bat', ps1: 'powershell', psd1: 'powershell', psm1: 'powershell',
+  c: 'c', h: 'c', cpp: 'cpp', cc: 'cpp', hpp: 'cpp', cs: 'csharp',
+  css: 'css', scss: 'scss', less: 'less',
+  go: 'go', rs: 'rust', java: 'java', kt: 'kotlin', swift: 'swift',
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript',
+  ts: 'typescript', mts: 'typescript', cts: 'typescript', tsx: 'typescript',
+  json: 'json', jsonc: 'jsonc', yml: 'yaml', yaml: 'yaml', toml: 'toml', ini: 'ini',
+  md: 'markdown', markdown: 'markdown', rst: 'rst',
+  py: 'python', rb: 'ruby', php: 'php', pl: 'perl', lua: 'lua',
+  sh: 'bash', bash: 'bash', zsh: 'bash', fish: 'bash',
+  sql: 'sql', xml: 'xml', html: 'html', htm: 'html', vue: 'vue', svelte: 'svelte',
+  diff: 'diff', patch: 'diff', csv: 'csv', tsv: 'tsv',
+}
+
+/**
+ * Guess the grammar hint from a path's extension.
+ * @param path - the remote path as authored.
+ * @returns the language id, or undefined to keep the block plain.
+ */
+function langOf(path: string): string | undefined {
+  const dot = path.lastIndexOf('.')
+  if (dot < 0) return undefined
+  const ext = path.slice(dot + 1).toLowerCase()
+  return Object.hasOwn(LANG_BY_EXTENSION, ext) ? LANG_BY_EXTENSION[ext] : undefined
+}
+
+/** Localized chrome for {@link ReadBlock}. */
+function readLabels(): ReadBlockLabels {
+  return {
+    codeLabel: tt('tool.codeLabel'),
+    wrapLabel: tt('tool.wrapLabel'),
+    unwrapLabel: tt('tool.unwrapLabel'),
+    window: (shown, total) => tt('tool.window', { shown, total }),
+    copy: tt('tool.copy'),
+    copied: tt('tool.copied'),
+    collapseAria: tt('tool.collapseAria'),
+    expandAria: hidden => tt('tool.expandAria', { hidden }),
+    collapse: tt('tool.collapse'),
+    expand: hidden => tt('tool.expand', { hidden }),
+  }
+}
+
+/** Localized chrome for {@link DiffBlock}. */
+function diffLabels(): DiffBlockLabels {
+  return {
+    codeLabel: tt('tool.codeLabel'),
+    wrapLabel: tt('tool.wrapLabel'),
+    unwrapLabel: tt('tool.unwrapLabel'),
+    copy: tt('tool.copy'),
+    copied: tt('tool.copied'),
+    collapseAria: tt('tool.collapseAria'),
+    expandAria: hidden => tt('tool.expandAria', { hidden }),
+    collapse: tt('tool.collapse'),
+    expand: hidden => tt('tool.expand', { hidden }),
+  }
+}
+
+/** One-line row for a call that failed: the message replaces the card. */
+function Row(props: { title: string; detail: string }) {
+  return (
+    <div className={css.rowError}>
+      <span className={css.title}>{props.title}</span>
+      {props.detail !== '' && <span className={css.detail}>{props.detail}</span>}
+    </div>
+  )
+}
+
+/** Read the persisted metadata off a settled result node. */
+function metaOf(block: unknown): unknown {
+  if (typeof block !== 'object' || block === null) return undefined
+  return (block as { meta?: unknown }).meta
+}
+
+/**
+ * The remote path a call named, read from its arguments.
+ *
+ * Available from the first dispatch onward, which is what keeps the header line
+ * stable across the running → settled transition: the row keeps saying which
+ * file it is working on instead of swapping its text when the result lands. A
+ * settled node carries the call head under `call`; a running one is the head.
+ * @param block - any phase of the Tool block.
+ * @returns the authored path, or undefined when none was named yet.
+ */
+function argsPath(block: unknown): string | undefined {
+  if (typeof block !== 'object' || block === null) return undefined
+  const record = block as { argsRaw?: unknown; call?: { argsRaw?: unknown } | null }
+  const head = record.call ?? record
+  if (typeof head.argsRaw !== 'string' || head.argsRaw === '') return undefined
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(head.argsRaw)
+  } catch {
+    return undefined
+  }
+  if (typeof parsed !== 'object' || parsed === null) return undefined
+  const path = (parsed as { remotePath?: unknown }).remotePath
+  return typeof path === 'string' && path !== '' ? path : undefined
+}
+
+/** Count the lines a hunk adds and removes. */
+function changedLines(card: DiffCardModel): { added: number; removed: number } {
+  let added = 0
+  let removed = 0
+  for (const hunk of card.hunks) {
+    added += hunk.newText === '' ? 0 : hunk.newText.split('\n').length
+    removed += hunk.oldText === '' ? 0 : hunk.oldText.split('\n').length
+  }
+  return { added, removed }
+}
+
+/** The `+n -m` figure a collapsed write or edit row shows beside its path. */
+function changedTotals(card: DiffCardModel): { added: number; removed: number } | undefined {
+  const totals = changedLines(card)
+  return totals.added === 0 && totals.removed === 0 ? undefined : totals
+}
+
+/** The summary line a write or edit card shows under its diff. */
+function diffSummary(card: DiffCardModel): string {
+  const parts: string[] = []
+  if (card.tool === 'write') {
+    parts.push(tt(card.operation === 'create' ? 'tool.created' : 'tool.updated', { bytes: card.bytes }))
+  } else {
+    parts.push(tt('tool.replacements', { count: card.replacements }))
+  }
+  if (card.encoding !== 'utf8') parts.push(card.encoding)
+  if (card.beyondBasis) parts.push(tt('tool.beyondBasis'))
+  return parts.join(' · ')
+}
+
+/**
+ * One collapsed file row that expands into a card.
+ * @param props - the disclosure state, the header material, and the card body.
+ * @returns the disclosure row, body included only while expanded.
+ */
+function FileDisclosure(props: {
+  path: string
+  title: string
+  meta?: string | undefined
+  diff?: { added: number; removed: number } | undefined
+  open: boolean
+  expandable: boolean
+  running?: boolean
+  onToggle: () => void
+  children: ReactNode
+}) {
+  const meta = props.meta ?? ''
+  const hasPath = props.path !== ''
+  return (
+    <div className={css.wrap}>
+      <DisclosureRow
+        icon={<FileTypeIcon path={props.path} size={14} />}
+        title={props.title}
+        open={props.open}
+        expandable={props.expandable}
+        running={props.running ?? false}
+        expandOnRowClick={props.expandable}
+        onToggle={props.onToggle}
+        collapsedContent={hasPath || meta !== '' ? (
+          <>
+            {hasPath && <span className={css.sep} aria-hidden />}
+            {hasPath && <span className={css.summary}>{props.path}</span>}
+            {meta !== '' && <span className={css.meta}>{meta}</span>}
+            {props.diff !== undefined && (
+              <span className={css.diffStat}>
+                <span className={css.added}>{`+${props.diff.added}`}</span>{' '}
+                <span className={css.removed}>{`-${props.diff.removed}`}</span>
+              </span>
+            )}
+          </>
+        ) : undefined}
+      >
+        {props.children}
+      </DisclosureRow>
+    </div>
+  )
+}
+
+/** Render the settled read card. */
+function ReadView(props: { card: ReadCardModel; open: boolean; onToggle: () => void }) {
+  const { card, open, onToggle } = props
+  const notes: string[] = []
+  if (card.truncatedByBytes) notes.push(tt('tool.truncatedByBytes'))
+  if (card.truncatedLines > 0) notes.push(tt('tool.truncatedLines', { count: card.truncatedLines }))
+  if (card.encoding !== 'utf8') notes.push(card.encoding)
+  return (
+    <FileDisclosure
+      path={card.path}
+      title={tt('tool.read')}
+      meta={tt('tool.lines', { count: card.totalLines })}
+      open={open}
+      expandable
+      onToggle={onToggle}
+    >
+      <ReadBlock
+        label={card.path}
+        lines={card.lines}
+        totalLines={card.totalLines}
+        lang={langOf(card.path)}
+        labels={readLabels()}
+        maxLines={CHAT_READ_MAX_LINES}
+      />
+      {notes.length > 0 && <div className={css.note}>{notes.join(' · ')}</div>}
+    </FileDisclosure>
+  )
+}
+
+/** Render the settled write or edit card. */
+function DiffView(props: { card: DiffCardModel; open: boolean; onToggle: () => void }) {
+  const { card, open, onToggle } = props
+  // The primitive takes `oldText: null` to mean "no prior content", which is a
+  // create; the host writes '' for that case so the two stay JSON-friendly.
+  const diffs: DiffHunk[] = card.hunks.map(hunk => ({
+    path: card.path,
+    oldText: hunk.oldText === '' ? null : hunk.oldText,
+    newText: hunk.newText,
+  }))
+  return (
+    <FileDisclosure
+      path={card.path}
+      title={tt(card.tool === 'write' ? 'tool.write' : 'tool.edit')}
+      diff={changedTotals(card)}
+      open={open}
+      expandable={diffs.length > 0}
+      onToggle={onToggle}
+    >
+      {diffs.length > 0 && (
+        <DiffBlock diffs={diffs} labels={diffLabels()} maxLines={CHAT_DIFF_MAX_LINES} />
+      )}
+      <div className={css.note}>{diffSummary(card)}</div>
+    </FileDisclosure>
+  )
+}
+
+/** Shared driver: one card per stage, with the model built from the metadata. */
+function FileCardView(props: WinrmFileCardProps & { tool: 'read' | 'write' | 'edit' }) {
+  const { phase, block, tool, useDisclosure } = props
+  const disclosure = useDisclosure()
+  const title = tt(`tool.${tool}`)
+  const path = argsPath(block) ?? ''
+  if (phase !== 'result') {
+    return (
+      <FileDisclosure
+        path={path}
+        title={title}
+        meta={path === '' ? tt('tool.running') : undefined}
+        open={false}
+        expandable={false}
+        running
+        onToggle={() => {}}
+      >
+        {null}
+      </FileDisclosure>
+    )
+  }
+  const meta = metaOf(block)
+  const card = tool === 'read' ? readCard(meta, path) : diffCard(meta, path, tool)
+  if (card === undefined) {
+    return (
+      <FileDisclosure
+        path={path}
+        title={title}
+        meta={tt('tool.noDetail')}
+        open={false}
+        expandable={false}
+        onToggle={() => {}}
+      >
+        {null}
+      </FileDisclosure>
+    )
+  }
+  if (card.kind === 'error') return <Row title={title} detail={card.message} />
+  if (card.kind === 'read') {
+    return <ReadView card={card} open={disclosure.expanded} onToggle={disclosure.toggle} />
+  }
+  return <DiffView card={card} open={disclosure.expanded} onToggle={disclosure.toggle} />
+}
+
+/** Card for `winrm_read`. */
+export function WinrmReadCard(props: WinrmFileCardProps) {
+  return <FileCardView {...props} tool="read" />
+}
+
+/** Card for `winrm_write`. */
+export function WinrmWriteCard(props: WinrmFileCardProps) {
+  return <FileCardView {...props} tool="write" />
+}
+
+/** Card for `winrm_edit`. */
+export function WinrmEditCard(props: WinrmFileCardProps) {
+  return <FileCardView {...props} tool="edit" />
+}

package/src/diff.ts

@@ -0,0 +1,128 @@
+/**
+ * Contextual diff derivation for the write/edit presentation metadata.
+ *
+ * The GUI renders a diff card from `tool/result` metadata rather than from the
+ * model-facing text, so the hunks are projected here, at result time, and
+ * persisted with the session log. This mirrors the harness's own file tools:
+ * one entry per applied change with a few surrounding context lines.
+ *
+ * The alignment is deliberately cheap rather than a full LCS: common leading
+ * and trailing lines are trimmed, and when the remaining halves have the same
+ * length each differing run becomes its own hunk. That covers the cases these
+ * two tools actually produce — an exact-string edit, and a rewrite that keeps
+ * most lines — without a diff dependency in a plugin whose point is a small
+ * footprint. A rewrite that changes the line count collapses to one hunk over
+ * the changed span, which is still a truthful summary.
+ * @module dsh-winrm/src/diff
+ */
+
+/** Context lines shown on each side of an applied hunk. */
+export const DIFF_CONTEXT = 3
+
+/**
+ * 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.
+ */
+export const DIFF_BASIS_MAX_BYTES = 256 * 1024
+
+/**
+ * Largest serialized hunk list kept on one result. A pathological edit (a
+ * whole-file rewrite of a large file) can produce thousands of hunks; past
+ * this bound the card degrades to path-only instead of bloating the log.
+ */
+export const DIFF_META_MAX_BYTES = 512 * 1024
+
+/**
+ * One applied hunk: the fragment before the change and after it.
+ *
+ * Declared as a type alias rather than an interface so it satisfies the
+ * `JsonValue` index signature the tool-output metadata is typed against.
+ */
+export type RemoteFileDiff = {
+  /** Remote path the hunk belongs to (the authored argument). */
+  path: string
+  /** Prior content including context lines; empty for a pure insertion. */
+  oldText: string
+  /** Content after the change, including the shared context lines. */
+  newText: string
+}
+
+/** Split text into lines, treating every terminator as a separator. */
+function toLines(text: string): string[] {
+  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.
+ */
+export function computeHunkDiffs(path: string, before: string, after: string): RemoteFileDiff[] {
+  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: number, to: number): RemoteFileDiff => {
+    // Both mid arrays have the same length in the aligned branch below, so one
+    // clamped window addresses the old and the new side alike.
+    const start = Math.max(0, from - DIFF_CONTEXT)
+    const stop = Math.min(oldMid.length, to + DIFF_CONTEXT)
+    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) {
+    // Unaligned rewrite: one hunk over the whole changed span.
+    return [{
+      path,
+      oldText: oldLines.slice(Math.max(0, head - DIFF_CONTEXT), oldLines.length - Math.max(0, tail - DIFF_CONTEXT)).join('\n'),
+      newText: newLines.slice(Math.max(0, head - DIFF_CONTEXT), newLines.length - Math.max(0, tail - DIFF_CONTEXT)).join('\n'),
+    }]
+  }
+
+  const diffs: RemoteFileDiff[] = []
+  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.
+ */
+export function boundedHunkDiffs(path: string, before: string, after: string): RemoteFileDiff[] {
+  const diffs = computeHunkDiffs(path, before, after)
+  if (diffs.length === 0) return diffs
+  return JSON.stringify(diffs).length > DIFF_META_MAX_BYTES ? [] : diffs
+}

package/src/engine/client.ts

@@ -337,6 +337,41 @@ const STREAM_GZIP_MIN_RATIO = 0.85
 /** Per-Send HTTP budget; a single slice is small, so this only bounds a stalled connection. */
 const STREAM_SEND_TIMEOUT_MS = 120_000
 
+/**
+ * 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.
+ */
+export const STREAM_IDLE_TIMEOUT_MS = 180_000
+
+/**
+ * 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 = 65_536
+
+/**
+ * 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.
+ */
+export function transferBudget(bytes: number, idleMs = STREAM_IDLE_TIMEOUT_MS): { idleMs: number; hardMs: number } {
+  const optimisticMs = Math.ceil(Math.max(0, bytes) / STREAM_MIN_BYTES_PER_SEC) * 1000
+  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 →
@@ -349,7 +384,7 @@ const STREAM_SEND_TIMEOUT_MS = 120_000
  * @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.
@@ -360,7 +395,7 @@ async function streamOnce(
   remotePath: string,
   data: Buffer,
   onProgress: ((transferred: number, total: number) => void) | undefined,
-  timeoutMs: number,
+  budget: { idleMs: number; hardMs: number },
   authMethod: WinrmAuth,
   sendHttp: ReturnType<typeof loadSendHttp> & object,
 ): Promise<number> {
@@ -375,7 +410,12 @@ async function streamOnce(
     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
+  // Progress is what keeps a transfer alive: the send loop and the final
+  // receive loop both refresh this, and only a window with no progress at all
+  // is treated as a stall.
+  let lastProgressAt = Date.now()
+  const stalled = (): boolean => Date.now() - lastProgressAt >= budget.idleMs
   const state = { shellId: undefined as string | undefined, timedOut: false, settled: false }
   const total = data.length
 
@@ -405,7 +445,7 @@ async function streamOnce(
     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 })
@@ -422,6 +462,7 @@ async function streamOnce(
         throw error
       }
       offset += take
+      lastProgressAt = Date.now()
       onProgress?.(offset, total)
       if (slice < ceiling) slice = Math.min(ceiling, slice * 2)
     }
@@ -429,15 +470,15 @@ async function streamOnce(
     // 4. The receiver stops on its own once the declared byte count lands, so
     //    there is nothing to close — just wait for its envelope.
     const receive = { ...base, 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)
@@ -488,7 +529,7 @@ async function streamOnce(
  * @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.
  */
 export async function uploadStream(
@@ -496,15 +537,16 @@ export async function uploadStream(
   remotePath: string,
   data: Buffer,
   onProgress?: (transferred: number, total: number) => void,
-  timeoutMs = 600_000,
+  idleMs = STREAM_IDLE_TIMEOUT_MS,
 ): Promise<number | null> {
   const sendHttp = loadSendHttp()
   if (sendHttp === null) return null
+  const budget = transferBudget(data.length, idleMs)
   const candidates: WinrmAuth[] = conn.useHttps ? ['basic', 'ntlm'] : ['ntlm', 'basic']
   let lastError: unknown
   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
@@ -527,7 +569,7 @@ const DOWNLOAD_RECEIVE_TIMEOUT_MS = 120_000
  * @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.
@@ -538,7 +580,7 @@ async function downloadWorkerOnce(
   start: number,
   length: number,
   onData: (offset: number, data: Buffer) => void,
-  timeoutMs: number,
+  budget: { idleMs: number; hardMs: number },
   authMethod: WinrmAuth,
   sendHttp: ReturnType<typeof loadSendHttp> & object,
 ): Promise<number> {
@@ -553,7 +595,12 @@ async function downloadWorkerOnce(
     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
+  // Same rule as the upload path: bytes arriving keep the worker alive, and
+  // only a window with no bytes at all counts as a stall. A flat whole-transfer
+  // cap would fail a large file on a slow link even while it is moving.
+  let lastDataAt = Date.now()
+  const stalled = (): boolean => Date.now() - lastDataAt >= budget.idleMs
   const state = { shellId: undefined as string | undefined, timedOut: false, settled: false }
 
   const inner = async (): Promise<number> => {
@@ -589,7 +636,7 @@ async function downloadWorkerOnce(
       // A worker that lost the deadline race keeps running in the background
       // unless it checks; without this it would go on fetching and pushing
       // bytes into a file the caller has already given up on.
-      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) {
@@ -605,6 +652,7 @@ async function downloadWorkerOnce(
           stderr += stream.data.toString('utf8')
         }
       }
+      if (sawData) lastDataAt = Date.now()
       if (inflateError !== undefined) throw inflateError
       if (result.exitCode !== undefined) exitCode = result.exitCode
       // A finished command whose final response carried nothing means the
@@ -663,7 +711,7 @@ async function downloadWorkerOnce(
  * @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.
  */
 export async function downloadStream(
@@ -671,13 +719,15 @@ export async function downloadStream(
   remotePath: string,
   onData: (offset: number, data: Buffer) => void,
   onProgress?: (transferred: number, total: number) => void,
-  timeoutMs = 600_000,
+  idleMs = STREAM_IDLE_TIMEOUT_MS,
 ): Promise<number | null> {
   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
+  // The payload size, not a constant, is what sets a legitimate duration here.
+  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
@@ -708,7 +758,7 @@ export async function downloadStream(
         }
         await Promise.all(
           ranges.map(range =>
-            downloadWorkerOnce(conn, remotePath, range.start, range.length, report, timeoutMs, authMethod, sendHttp),
+            downloadWorkerOnce(conn, remotePath, range.start, range.length, report, budget, authMethod, sendHttp),
           ),
         )
         return transferred