dsh-winrm 0.2.0 → 0.3.1

package/lib/types/engine/client.d.ts

@@ -44,6 +44,53 @@ export declare function testConnection(conn: WinRMParams): Promise<{
     error?: string;
 }>;
 export declare const TRANSFER_CHUNK: number;
-export declare function remoteFileSize(conn: WinRMParams, remotePath: string, timeoutMs?: number): Promise<number>;
+/**
+ * Size of a remote file, or null when the path does not exist or is a
+ * directory. The distinction matters: a caller that treats "absent" as "empty"
+ * writes an empty local file and reports success for a download that copied
+ * nothing.
+ */
+export declare function remoteFileSize(conn: WinRMParams, remotePath: string, timeoutMs?: number): Promise<number | null>;
 export declare function downloadChunks(conn: WinRMParams, remotePath: string, onChunk: (b64: string, bytes: number) => void, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number>;
 export declare function uploadBuffer(conn: WinRMParams, remotePath: string, data: Buffer, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number>;
+/**
+ * Upload a buffer over a single WinRS stdin stream.
+ *
+ * This replaces the per-chunk shell cycle: one shell, one command and one
+ * `Send` per 256 KiB, against a receiver that drains the stream straight into
+ * the file. Measured at ~10 s for 2 MiB where the old path took 310 s.
+ *
+ * Returns null — rather than throwing — when the transport this path depends
+ * on is unavailable (a future `winrm-client` layout that drops the internal
+ * module it borrows), so the caller can fall back to {@link uploadBuffer}
+ * instead of failing the transfer.
+ * @param conn - connection parameters.
+ * @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.
+ * @returns bytes written, or null when the streaming path is unavailable.
+ */
+export declare function uploadStream(conn: WinRMParams, remotePath: string, data: Buffer, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number | null>;
+/**
+ * Stream a remote file to a consumer, in parallel byte ranges.
+ *
+ * The old path asked for 48 KiB per shell lifecycle, so a 2 MiB file cost 43
+ * round-trip cycles and 129 s. Measured against this target, one `Receive`
+ * returns at most 128 KiB no matter how large an envelope is declared, which
+ * makes a download latency-bound rather than bandwidth-bound; the fix is
+ * therefore to run several ranges at once. Each worker opens its own shell and
+ * streams its range gzip-compressed, and because ranges are absolute, the
+ * caller can place each piece by offset and completion order does not matter.
+ *
+ * The remote side compresses unconditionally: a compressible 16 MiB file
+ * arrives in one round trip (2.0 s), and an incompressible file was measured no
+ * slower than raw (9457 ms vs 9582 ms).
+ * @param conn - connection parameters.
+ * @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.
+ * @returns the number of bytes delivered, or null when streaming is unavailable.
+ */
+export declare function downloadStream(conn: WinRMParams, remotePath: string, onData: (offset: number, data: Buffer) => void, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number | null>;

package/lib/types/engine/wsman.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Raw WSMan `Send` for the streaming upload path.
+ *
+ * The bundled `winrm-client` can only put text on the WinRS stdin stream: its
+ * `doSendInput` base64-encodes the input *again* on top of whatever the caller
+ * already encoded, and it has no way to close the stream. Both are fatal for a
+ * bulk transfer — double base64 costs 1.78x the bytes on the wire, and a
+ * stdin stream that never ends cannot tell the remote receiver "that is all".
+ *
+ * This module therefore builds the `Send` envelope itself and posts it through
+ * the library's own `sendHttp`, which keeps Basic/NTLM/SPNEGO and the HTTPS
+ * options exactly as the rest of the transport uses them. The stream carries
+ * raw file bytes, so the wire cost is 1.0x plus the envelope.
+ *
+ * The library is reached through `createRequire` rather than a static import
+ * because `dist/src/utils/http.js` is an internal CommonJS path with no
+ * `exports` map behind it. `loadSendHttp` returns null when that path is gone
+ * (a future `winrm-client` layout change), which lets the caller fall back to
+ * the old chunked path instead of failing the transfer.
+ */
+/** Connection parameters for one target (mirrors `WinRMParams` in client.ts). */
+export interface WsmanTarget {
+    host: string;
+    port: number;
+    path: string;
+    username: string;
+    password: string;
+    authMethod: 'basic' | 'ntlm';
+    useHttps?: boolean;
+    rejectUnauthorized?: boolean;
+}
+/** `sendHttp` as the bundled library declares it. */
+type SendHttp = (data: string, host: string, port: number, path: string, username: string, password: string, authMethod: 'basic' | 'ntlm', timeout?: number, useHttps?: boolean, rejectUnauthorized?: boolean) => Promise<unknown>;
+/**
+ * Envelope ceiling declared on every Send, in bytes.
+ *
+ * This is what the *client* promises the server it will never exceed, and the
+ * server enforces its own `MaxEnvelopeSizekb` on top. 512000 is the value the
+ * target host reports, and it is far above the library's hardcoded 153600 —
+ * raising it is what makes 256 KiB chunks legal.
+ */
+export declare const WS_MAX_ENVELOPE_BYTES = 512000;
+/**
+ * Bytes of XML wrapper around one base64 chunk.
+ *
+ * Measured against the envelope this module emits: fixed header, selector set,
+ * body tags and the message id. Used to size chunks against the ceiling before
+ * sending, so a normal transfer never needs a size rejection to converge.
+ */
+export declare const SEND_ENVELOPE_OVERHEAD_BYTES = 1600;
+/** The largest raw slice whose base64 form still fits `WS_MAX_ENVELOPE_BYTES`. */
+export declare const MAX_SEND_SLICE_BYTES: number;
+/**
+ * Resolve the library's `sendHttp`, or null when the internal path is absent.
+ * @returns the send function, or null when it cannot be loaded.
+ */
+export declare function loadSendHttp(): SendHttp | null;
+/**
+ * Build one WSMan `Send` envelope carrying `chunk` on the stdin stream.
+ *
+ * The header mirrors what the library emits, with three deliberate changes:
+ * `MaxEnvelopeSize` is raised to `limit`, the `Send` action replaces the
+ * command's, and the stream body is the caller's base64 verbatim — no second
+ * encode. `Name="stdin"` and `CommandId` are what bind the bytes to the
+ * running receiver's standard input.
+ * @param shellId - target shell from `Shell.doCreateShell`.
+ * @param commandId - target command from `Command.doExecuteCommand`.
+ * @param chunk - raw bytes to place on the remote stdin stream.
+ * @param limit - envelope ceiling to declare.
+ * @returns the SOAP envelope as a UTF-8 string.
+ */
+export declare function buildSendEnvelope(shellId: string, commandId: string, chunk: Buffer, limit: number): string;
+/**
+ * Push one raw slice onto the remote stdin stream.
+ *
+ * A rejection here is safe to retry with a smaller slice: the server validates
+ * the envelope size before dispatching it to the shell, so nothing reached the
+ * receiver's stdin when the call fails on size.
+ * @param target - connection parameters (auth already selected).
+ * @param shellId - target shell.
+ * @param commandId - target command.
+ * @param chunk - raw bytes to send.
+ * @param sendHttp - the resolved library function.
+ * @param timeoutMs - per-request HTTP timeout.
+ */
+export declare function sendStdinChunk(target: WsmanTarget, shellId: string, commandId: string, chunk: Buffer, sendHttp: SendHttp, timeoutMs: number): Promise<void>;
+/**
+ * Whether a failed Send was refused for exceeding the envelope ceiling.
+ *
+ * WSMan reports this as a SOAP fault rather than a status code, and the exact
+ * wording differs between the HTTP and HTTPS stacks, so the test looks for any
+ * of the size-related phrasings plus the plain 413 status. It deliberately
+ * does not match a bare "size" in unrelated text.
+ * @param error - the rejection to classify.
+ * @returns true when retrying with a smaller slice is the right response.
+ */
+export declare function isEnvelopeTooLarge(error: unknown): boolean;
+/**
+ * Build one WSMan `Receive` envelope asking for stdout and stderr.
+ *
+ * The library's own `buildReceiveOutputRequest` cannot be reused here because
+ * it hardcodes `MaxEnvelopeSize` at 153600 in its shared header. Measured
+ * against this target, that ceiling is what caps each response at 128 KiB —
+ * raising it to 512000 lets one `Receive` return 128 KiB per stream, which is
+ * the most the server will put in a single response regardless.
+ * @param shellId - target shell.
+ * @param commandId - target command whose streams are wanted.
+ * @param limit - envelope ceiling to declare.
+ * @returns the SOAP envelope as a UTF-8 string.
+ */
+export declare function buildReceiveEnvelope(shellId: string, commandId: string, limit: number): string;
+/** One decoded `rsp:Stream` element from a Receive response. */
+export interface ReceivedStream {
+    /** `Name` attribute: `stdout` or `stderr`. */
+    name: string;
+    /** Decoded payload bytes; empty for a stream element that carried no text. */
+    data: Buffer;
+    /** True when the `End` attribute marks this stream closed. */
+    end: boolean;
+}
+/** A decoded Receive response: its streams plus the command's exit code once known. */
+export interface ReceiveResult {
+    streams: ReceivedStream[];
+    /** `rsp:CommandState.rsp:ExitCode`, or undefined while the command still runs. */
+    exitCode?: number;
+}
+/**
+ * Read the streams and exit code out of a Receive response.
+ *
+ * The library's `extractStreams` cannot be used for binary payloads: it decodes
+ * every stream through `extractText`, which falls back to `String(obj)` for an
+ * element that has attributes but no text node — turning the terminal
+ * `End="true"` marker into the literal string `'[object Object]'` — and the
+ * library's `doReceiveOutputNonBlocking` then `.trim()`s the decoded text,
+ * which would eat whitespace bytes at either end of a real payload. This
+ * reader keeps the distinction between "no text" (zero bytes) and "text" and
+ * never trims.
+ * @param response - the parsed XML object returned by `sendHttp`.
+ * @returns the decoded streams and exit code.
+ * @throws when a stream's text node cannot be decoded as base64.
+ */
+export declare function readReceiveResult(response: unknown): ReceiveResult;
+/**
+ * Fetch one Receive response for a running command.
+ * @param target - connection parameters (auth already selected).
+ * @param shellId - target shell.
+ * @param commandId - target command.
+ * @param sendHttp - the resolved library function.
+ * @param timeoutMs - per-request HTTP timeout.
+ * @returns the decoded streams and exit code.
+ */
+export declare function receiveOutput(target: WsmanTarget, shellId: string, commandId: string, sendHttp: SendHttp, timeoutMs: number): Promise<ReceiveResult>;
+export {};

package/lib/types/engine.d.ts

@@ -1,9 +1,9 @@
 /**
  * The WinRM engine facade: host lookup, PowerShell exec (UTF-8 envelope),
- * service & process management, directory listing, base64-chunked file
- * transfer, cluster execution and the streaming console. The heavy lifting
- * lives in engine/ (client, console); this class composes them behind one
- * WinRmEngine instance per plugin apply.
+ * service & process management, directory listing, file transfer, cluster
+ * execution and the streaming console. The heavy lifting lives in engine/
+ * (client, console); this class composes them behind one WinRmEngine instance
+ * per plugin apply.
  */
 import type { ClusterResult, ExecResult, ProcessInfo, RemoteDirEntry, ServiceInfo, TestResult, TransferProgress, WinHostSummary } from './protocol.ts';
 import type { HostStore } from './store.ts';

package/lib/types/index.d.ts

@@ -1,16 +1,17 @@
 /**
  * dsh-winrm — host half. Mounts the WinRM engine (per-call PowerShell
  * execution with a UTF-8 envelope, streaming console, service/process
- * management, base64-chunked file transfer, cluster), the /api/dsh-winrm
+ * management, streamed file transfer, cluster), the /api/dsh-winrm
  * route family plus the console WebSocket upgrade, the agent tools
  * (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_upload,
  * winrm_download, winrm_cluster), and a system-prompt announcement. The
  * browser half (./client) renders the host manager and operations panel.
  * Everything rides official NPM SDK packages — no dsh source changes.
  *
- * Config is read live through `Volatile` references (`.get()`), so the
- * Settings page can flip `enabled` / `announceToAgent` without remounting;
- * `loader/volatile-update` re-runs the registration sync when they change.
+ * Config is read live through `Volatile` references (`.get()`), so editing
+ * `enabled` / `announceToAgent` in the profile takes effect without
+ * remounting; `loader/volatile-update` re-runs the registration sync when
+ * they change.
  */
 import type { Context, Volatile } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
@@ -33,7 +34,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     enabled: z<boolean, boolean, "volatile-defined">;
 }>>, "plain">;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export declare const WINRM_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-winrm \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B Windows \u8FD0\u7EF4\uFF0CWinRM/PowerShell Remoting\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CWindows\u300D\u5165\u53E3\uFF1B\u4EFF\u7167 dsh-ssh \u63D2\u4EF6\u5F00\u53D1\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 ~/.dsh/dsh-winrm.json\uFF08GUI \u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF09\uFF1Bwinrm_list \u5217\u51FA\u4E3B\u673A\u3001winrm_exec \u6267\u884C PowerShell \u547D\u4EE4\uFF08UTF-8 \u4FE1\u5C01\uFF0C\u4E2D\u6587\u4E0D\u4E71\u7801\uFF09\u3001winrm_service \u670D\u52A1\u7BA1\u7406\uFF08start/stop/restart/\u542F\u52A8\u7C7B\u578B\uFF09\u3001winrm_process \u8FDB\u7A0B\u7BA1\u7406\uFF08list/kill\uFF09\u3001winrm_upload/winrm_download \u6587\u4EF6\u4F20\u8F93\uFF08base64 \u5206\u5757\uFF0C\u65E0 SMB \u4F9D\u8D56\uFF09\u3001winrm_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1BWeb \u63A7\u5236\u53F0\u8D70 WebSocket\u3002\u8BA4\u8BC1\uFF1A\u901A\u8FC7\u539F\u751F Node.js WinRM \u5BA2\u6237\u7AEF\uFF08winrm-client\uFF09\u7684 NTLM/Negotiate \u4E0E Basic \u5B9E\u73B0\uFF0C\u517C\u5BB9\u672C\u5730\u8D26\u6237\u4E0E\u57DF\u8D26\u6237\uFF1B\u4F20\u8F93\u652F\u6301 http(5985)/https(5986)\u3002\u524D\u63D0\uFF1A\u76EE\u6807\u673A\u9700\u542F\u7528 WinRM\uFF08scripts/enable-winrm.ps1\uFF09\uFF0C\u672C\u673A\u65E0\u9700 Python \u2014\u2014 WinRM \u8D70\u7EAF Node \u4F9D\u8D56\u3002HTTP \u4EC5\u5EFA\u8BAE\u53D7\u4FE1\u5185\u7F51\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u7528\u6237\u63D0\u5230\u300CWindows \u670D\u52A1\u5668 / WinRM / PowerShell \u8FDC\u7A0B / \u670D\u52A1\u7BA1\u7406 / \u8FDB\u7A0B\u7BA1\u7406\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const WINRM_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-winrm \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B Windows \u8FD0\u7EF4\uFF0CWinRM/PowerShell Remoting\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CWindows\u300D\u5165\u53E3\uFF1B\u4EFF\u7167 dsh-ssh \u63D2\u4EF6\u5F00\u53D1\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 ~/.dsh/dsh-winrm.json\uFF08GUI \u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF09\uFF1Bwinrm_list \u5217\u51FA\u4E3B\u673A\u3001winrm_exec \u6267\u884C PowerShell \u547D\u4EE4\uFF08UTF-8 \u4FE1\u5C01\uFF0C\u4E2D\u6587\u4E0D\u4E71\u7801\uFF09\u3001winrm_service \u670D\u52A1\u7BA1\u7406\uFF08start/stop/restart/\u542F\u52A8\u7C7B\u578B\uFF09\u3001winrm_process \u8FDB\u7A0B\u7BA1\u7406\uFF08list/kill\uFF09\u3001winrm_upload/winrm_download \u6587\u4EF6\u4F20\u8F93\uFF08SMB \u7BA1\u7406\u5171\u4EAB\u53EF\u8FBE\u65F6\u4F18\u5148\uFF0C\u5426\u5219\u8D70 WinRM \u6D41\u5F0F\u4F20\u8F93\uFF0C\u65E0 SMB \u4F9D\u8D56\uFF0C\u5927\u6587\u4EF6\u7ECF SHA256 \u6821\u9A8C\uFF09\u3001winrm_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1BWeb \u63A7\u5236\u53F0\u8D70 WebSocket\u3002\u8BA4\u8BC1\uFF1A\u901A\u8FC7\u539F\u751F Node.js WinRM \u5BA2\u6237\u7AEF\uFF08winrm-client\uFF09\u7684 NTLM/Negotiate \u4E0E Basic \u5B9E\u73B0\uFF0C\u517C\u5BB9\u672C\u5730\u8D26\u6237\u4E0E\u57DF\u8D26\u6237\uFF1B\u4F20\u8F93\u652F\u6301 http(5985)/https(5986)\u3002\u524D\u63D0\uFF1A\u76EE\u6807\u673A\u9700\u542F\u7528 WinRM\uFF08scripts/enable-winrm.ps1\uFF09\uFF0C\u672C\u673A\u65E0\u9700 Python \u2014\u2014 WinRM \u8D70\u7EAF Node \u4F9D\u8D56\u3002HTTP \u4EC5\u5EFA\u8BAE\u53D7\u4FE1\u5185\u7F51\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u7528\u6237\u63D0\u5230\u300CWindows \u670D\u52A1\u5668 / WinRM / PowerShell \u8FDC\u7A0B / \u670D\u52A1\u7BA1\u7406 / \u8FDB\u7A0B\u7BA1\u7406\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 /**
  * Mount the WinRM engine, routes, tools, and announcement.
  * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

package/lib/types/powershell.d.ts

@@ -55,6 +55,13 @@ export declare function encodeCommand(script: string): string;
  * ~8191-character cap is the whole point of the stdin channel.
  */
 export declare function powershellCommandLine(): string;
+/**
+ * The constant powershell.exe command line for a streaming upload.
+ *
+ * The receiver travels on stdin right behind it, so this stays well clear of
+ * cmd.exe's cap and does not change when the receiver does.
+ */
+export declare function streamCommandLine(): string;
 /**
  * The stdin payload for one command: the UTF-8 **byte** count, a newline, then
  * the raw script.
@@ -87,7 +94,12 @@ export declare function psListProcesses(): string;
 export declare function psKillProcess(id: number): string;
 /** JSON: directory listing. */
 export declare function psListDir(dir: string): string;
-/** Plain: remote file size in bytes (0 when missing). */
+/**
+ * Plain: remote file size in bytes. Emits nothing at all when the path is
+ * missing or is a directory, so the caller can tell "absent" from "empty" —
+ * both used to collapse to the string "0", which made a download of a
+ * nonexistent file look like a successful transfer of a zero-byte one.
+ */
 export declare function psFileSize(p: string): string;
 /** Plain: base64 of up to `count` bytes at `offset` (download chunk). */
 export declare function psReadChunk(p: string, offset: number, count: number): string;
@@ -96,6 +108,103 @@ export declare function psReadChunk(p: string, offset: number, count: number): s
  * prints the number of bytes written.
  */
 export declare function psWriteChunk(p: string, b64: string, append: boolean): string;
+/** Magic stamped into the frame header that precedes every stream chunk. */
+export declare const STREAM_FRAME_MAGIC = "DSHZ";
+/** Frame header size: 4 magic bytes + 4 little-endian length bytes + 1 mode byte + 1 reserved. */
+export declare const STREAM_FRAME_HEADER_BYTES = 10;
+/** Frame mode: the payload after the header is a gzip member. */
+export declare const STREAM_FRAME_GZIP = 1;
+/** Frame mode: the payload after the header is raw file bytes. */
+export declare const STREAM_FRAME_RAW = 0;
+/** Frame mode: the payload after the header is the transfer's metadata. */
+export declare const STREAM_FRAME_HEADER = 2;
+/**
+ * Wrap one payload in a stream frame: `DSHZ` + uint32LE length + mode + pad.
+ *
+ * The frame is what makes a compressed stream legal on a pipe. stdin cannot
+ * seek, so the receiver has to be handed the exact byte count of the next gzip
+ * member before it lets `GZipStream` touch it; otherwise the inflater would
+ * read into the member that follows and the stream would desynchronize. The
+ * mode byte travels with the payload so the client can switch between gzip and
+ * raw per chunk.
+ * @param payload - gzip member bytes or raw file bytes.
+ * @param mode - `STREAM_FRAME_GZIP` or `STREAM_FRAME_RAW`.
+ * @returns the framed chunk to place on the stdin stream.
+ */
+export declare function buildStreamFrame(payload: Buffer, mode: number): Buffer;
+/**
+ * Streaming receiver: drain framed stdin chunks into the file named by the
+ * header frame, until the declared byte count lands.
+ *
+ * This is the fast upload path. Instead of shipping base64 text inside a
+ * PowerShell script — which costs one full shell create/command/delete cycle
+ * per 48 KiB — the remote shell starts this script once and the client then
+ * pushes bytes straight down the WinRS stdin stream. The only per-chunk cost
+ * left is a single `Send`, so a whole file costs one shell and one command no
+ * matter how large it is.
+ *
+ * The script deliberately takes **no arguments**. The destination path and
+ * total byte count arrive as the first frame on stdin, which keeps the command
+ * line a constant size: WinRS hands the command line to cmd.exe, whose limit
+ * is about 8191 characters, and a long remote path interpolated into the
+ * script would eat into that budget (the script is base64-of-UTF-16 on the
+ * wire, so every character costs 2.67). Reading them from the stream removes
+ * the limit entirely and mirrors how `powershellCommandLine` stays constant.
+ *
+ * Every wire chunk is a frame: `DSHZ` + 4-byte little-endian payload length +
+ * 1 mode byte + 1 reserved, followed by exactly that many payload bytes. The
+ * explicit frame is what makes a *pipe* usable for a compressed stream: stdin
+ * cannot seek, so the receiver must be told how long the next gzip member is
+ * before it hands the bytes to `GZipStream`, or the inflater would read into
+ * the member that follows. The mode byte lets the client pick per chunk — gzip
+ * when it actually shrinks the data, raw bytes when it would not — so
+ * incompressible files never pay compression overhead.
+ *
+ * The script prints the three-line envelope on stdout with the byte count as
+ * its payload, so the caller can prove the transfer landed complete.
+ * @returns a PowerShell script suitable for `-EncodedCommand`.
+ */
+export declare function psReceiveStream(): string;
+/**
+ * Streaming sender: write one byte range of the file to standard output,
+ * gzip-compressed, for the download path.
+ *
+ * This is the mirror of {@link psReceiveStream}. The old download path asked
+ * for 48 KiB at a time, and every chunk cost a full shell create / command /
+ * delete cycle — five HTTP round trips each — so a 2 MiB file took 129 s. Here
+ * the shell is created once and the client then simply receives; the only
+ * per-chunk cost left is one `Receive`, and the target streams the file as fast
+ * as the transport will drain it.
+ *
+ * Two details make this work:
+ *
+ * - **Only stderr may carry text.** Anything written to the PowerShell success
+ *   stream would be merged into the payload and corrupt the file, so the byte
+ *   count and any error go to `[Console]::Error` and the exit code, not stdout.
+ * - **The range is positional.** `Position` plus a byte count lets several
+ *   shells serve different parts of one file concurrently; each writes to its
+ *   own offset on the client, so completion order does not matter.
+ *
+ * Output is gzip-compressed unconditionally. Measured against this target, a
+ * compressible 16 MiB file collapsed from 121 round trips to 1 (2.0 s), and an
+ * incompressible 2 MiB file was no slower than raw (9457 ms vs 9582 ms), so the
+ * compression pays for itself or costs nothing.
+ * @param remotePath - file to read on the target.
+ * @param start - first byte offset of this worker's range.
+ * @param length - number of bytes this worker must send.
+ * @returns a PowerShell script suitable for `-EncodedCommand`.
+ */
+export declare function psSendStream(remotePath: string, start: number, length: number): string;
+/**
+ * Wrap an arbitrary script in the constant powershell.exe invocation.
+ *
+ * Only safe for scripts that fit cmd.exe's ~8191 character command line (the
+ * script is base64-of-UTF-16 on the wire, so it costs 2.67 characters each);
+ * {@link psReceiveStream} outgrew that and travels on stdin instead.
+ * @param script - the PowerShell script to run.
+ * @returns the command line to hand to WinRS.
+ */
+export declare function scriptCommandLine(script: string): string;
 /**
  * Parse the three-line envelope: { exitCode, stdout, stderr } or null when absent.
  *

package/lib/types/smb.d.ts

@@ -1,11 +1,11 @@
 /**
  * SMB transfer bridge.
  *
- * The WinRM base64 chunk bridge is reliable for small files but breaks for
- * large artifacts (the WinRM/HTTP envelope rejects large payloads), so whole
- * files ride the remote admin share. This module mounts the remote host's
- * admin share with `net use` (password passed via stdin, never argv), copies
- * whole files with node:fs, then verifies the SHA-256 on both ends.
+ * SMB is the fast channel when the admin share is reachable, so `auto` tries it
+ * first and falls back to the WinRM streaming path. This module mounts the
+ * remote host's admin share with `net use` (password passed via stdin, never
+ * argv), copies whole files with node:fs, then verifies the SHA-256 on both
+ * ends.
  */
 import type { WinHostEntry } from './protocol.ts';
 /** Per-transfer channel selector. */
@@ -19,6 +19,25 @@ export interface SmbTransferResult {
  * D:\\dir\\file -> \\\\host\\D$\\dir\\file
  */
 export declare function adminSharePath(host: string, remotePath: string): string;
+/**
+ * Whether the target's SMB port (445) accepts a connection.
+ *
+ * `net use` is the only way to mount the admin share, but it has no useful
+ * timeout: against a host whose 445 is filtered or whose SMB service is down it
+ * spends a full minute before failing. That minute was being paid on *every*
+ * `auto` upload before the WinRM fallback could even start — measured at 61 s
+ * and 58 s on the test host, against a 12 s streaming transfer. A bare TCP
+ * connect answers the same question in milliseconds.
+ *
+ * A negative verdict is cached briefly so a burst of transfers does not re-probe
+ * for each one; a positive verdict is cached too, but the `net use` that follows
+ * still reports its own failure if the share turns out to be unmountable.
+ * @param host - target hostname or address.
+ * @returns true when port 445 accepted a connection.
+ */
+export declare function smbReachable(host: string): Promise<boolean>;
+/** Error thrown when SMB was requested or probed and the target is not listening. */
+export declare function smbUnavailable(host: string): Error;
 /**
  * Copy one local file to a remote Windows host over SMB, verifying the
  * remote SHA-256 matches the local source.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-winrm",
-  "description": "Remote Windows administration for the dsh web GUI: WinRM/PowerShell Remoting host config store (~/.dsh/dsh-winrm.json), PowerShell exec / streaming console / service & process management / base64-chunked file transfer / cluster execution, plus agent tools (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_upload, winrm_download, winrm_cluster). Runs entirely on a native Node.js WinRM client (winrm-client) — no Python/pywinrm required. Standalone Cordis plugin — mounted via cordis.patch.yml + a profile node_modules link, no dsh source changes.",
-  "version": "0.2.0",
+  "description": "Remote Windows administration for the dsh web GUI: WinRM/PowerShell Remoting host config store (~/.dsh/dsh-winrm.json), PowerShell exec / streaming console / service & process management / streamed file transfer / cluster execution, plus agent tools (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_upload, winrm_download, winrm_cluster). Runs entirely on a native Node.js WinRM client (winrm-client) — no Python/pywinrm required. Standalone Cordis plugin — mounted via cordis.patch.yml + a profile node_modules link, no dsh source changes.",
+  "version": "0.3.1",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {