dsh-winrm 0.3.1 → 0.4.0

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

@@ -113,6 +113,28 @@ export declare const zh: {
     readonly 'transfer.mib': "MB";
     readonly 'transfer.dir': "目录";
     readonly 'transfer.file': "文件";
+    readonly 'tool.read': "读取远程文件";
+    readonly 'tool.write': "写入远程文件";
+    readonly 'tool.edit': "编辑远程文件";
+    readonly 'tool.running': "执行中…";
+    readonly 'tool.noDetail': "无卡片数据";
+    readonly 'tool.created': "新建 {bytes} 字节";
+    readonly 'tool.updated': "覆盖 {bytes} 字节";
+    readonly 'tool.replacements': "替换 {count} 处";
+    readonly 'tool.beyondBasis': "文件超过 diff 体积上限，仅显示路径";
+    readonly 'tool.truncatedByBytes': "已按字节上限截断";
+    readonly 'tool.truncatedLines': "{count} 行过长已截断";
+    readonly 'tool.codeLabel': "代码";
+    readonly 'tool.wrapLabel': "自动换行";
+    readonly 'tool.unwrapLabel': "取消自动换行";
+    readonly 'tool.window': "第 {shown} / {total} 行";
+    readonly 'tool.lines': "共 {count} 行";
+    readonly 'tool.copy': "复制";
+    readonly 'tool.copied': "已复制";
+    readonly 'tool.collapseAria': "收起";
+    readonly 'tool.expandAria': "展开剩余 {hidden} 行";
+    readonly 'tool.collapse': "收起";
+    readonly 'tool.expand': "展开其余 {hidden} 行";
 };
 export declare const en: {
     readonly 'entry.label': "Windows";
@@ -225,6 +247,28 @@ export declare const en: {
     readonly 'transfer.mib': "MB";
     readonly 'transfer.dir': "dir";
     readonly 'transfer.file': "file";
+    readonly 'tool.read': "Read remote file";
+    readonly 'tool.write': "Write remote file";
+    readonly 'tool.edit': "Edit remote file";
+    readonly 'tool.running': "Working…";
+    readonly 'tool.noDetail': "No card data";
+    readonly 'tool.created': "Created {bytes} bytes";
+    readonly 'tool.updated': "Overwrote {bytes} bytes";
+    readonly 'tool.replacements': "{count} replacements";
+    readonly 'tool.beyondBasis': "File is past the diff size cap; showing the path only";
+    readonly 'tool.truncatedByBytes': "Cut at the byte budget";
+    readonly 'tool.truncatedLines': "{count} long lines truncated";
+    readonly 'tool.codeLabel': "Code";
+    readonly 'tool.wrapLabel': "Wrap lines";
+    readonly 'tool.unwrapLabel': "Do not wrap";
+    readonly 'tool.window': "{shown} of {total} lines";
+    readonly 'tool.lines': "{count} lines";
+    readonly 'tool.copy': "Copy";
+    readonly 'tool.copied': "Copied";
+    readonly 'tool.collapseAria': "Collapse";
+    readonly 'tool.expandAria': "Expand the remaining {hidden} lines";
+    readonly 'tool.collapse': "Collapse";
+    readonly 'tool.expand': "Show the remaining {hidden} lines";
 };
 export type WinKey = keyof typeof zh;
 /** Translate a key in one dictionary with optional {name} params. */

package/lib/types/client/tool/card-model.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Card models for the three remote file tools.
+ *
+ * The host projects a small JSON payload through `output.presentationMeta` and
+ * the session log persists it; these functions narrow that unknown payload into
+ * something the card components can hand to the harness's `ReadBlock` and
+ * `DiffBlock` primitives. Kept apart from the components so the narrowing can be
+ * unit tested without a DOM.
+ * @module dsh-winrm/src/client/tool/card-model
+ */
+/** One line of a read window. */
+export interface ReadCardLine {
+    number: number;
+    text: string;
+}
+/** A completed `winrm_read`: a line-numbered window of a remote file. */
+export interface ReadCard {
+    kind: 'read';
+    path: string;
+    offset: number;
+    lines: ReadCardLine[];
+    totalLines: number;
+    encoding: string;
+    truncatedByBytes: boolean;
+    truncatedLines: number;
+}
+/** One hunk of a remote write or edit, in the primitive's own shape. */
+export interface DiffHunk {
+    /** Prior fragment including shared context; `''` when the hunk had no prior content. */
+    oldText: string;
+    /** Resulting fragment including the same shared context. */
+    newText: string;
+}
+/** A completed `winrm_write` or `winrm_edit`: the changes it applied. */
+export interface DiffCard {
+    kind: 'diff';
+    /** Which tool produced it, so the header can name the operation. */
+    tool: 'write' | 'edit';
+    path: string;
+    operation: 'create' | 'update';
+    bytes: number;
+    size: number;
+    replacements: number;
+    encoding: string;
+    hunks: DiffHunk[];
+    /** True when the previous text was past the basis cap, so no hunks exist. */
+    beyondBasis: boolean;
+}
+/** A failed call: keeps the path and the message, drops card-specific detail. */
+export interface ErrorCard {
+    kind: 'error';
+    path: string;
+    message: string;
+}
+/** Any card these tools render. */
+export type FileCard = ReadCard | DiffCard | ErrorCard;
+/**
+ * Narrow a `winrm_read` metadata payload into a card.
+ * @param meta - the persisted payload, of unknown shape.
+ * @param fallbackPath - the authored path, used when the payload omits one.
+ * @returns the card, or `undefined` when the payload is not a read card.
+ */
+export declare function readCard(meta: unknown, fallbackPath: string): FileCard | undefined;
+/**
+ * Narrow a `winrm_write` / `winrm_edit` metadata payload into a card.
+ * @param meta - the persisted payload, of unknown shape.
+ * @param fallbackPath - the authored path, used when the payload omits one.
+ * @param tool - which tool produced the payload.
+ * @returns the card, or `undefined` when the payload belongs to another card.
+ */
+export declare function diffCard(meta: unknown, fallbackPath: string, tool: 'write' | 'edit'): FileCard | undefined;

package/lib/types/client/tool/cards.d.ts

@@ -0,0 +1,9 @@
+import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client';
+/** The Tool view props these cards read. */
+export type WinrmFileCardProps = ToolCallViewProps;
+/** Card for `winrm_read`. */
+export declare function WinrmReadCard(props: WinrmFileCardProps): import("react").JSX.Element;
+/** Card for `winrm_write`. */
+export declare function WinrmWriteCard(props: WinrmFileCardProps): import("react").JSX.Element;
+/** Card for `winrm_edit`. */
+export declare function WinrmEditCard(props: WinrmFileCardProps): import("react").JSX.Element;

package/lib/types/diff.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 declare 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 declare const DIFF_BASIS_MAX_BYTES: number;
+/**
+ * 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 declare const DIFF_META_MAX_BYTES: number;
+/**
+ * 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;
+};
+/**
+ * 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 declare function computeHunkDiffs(path: string, before: string, after: string): RemoteFileDiff[];
+/**
+ * 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 declare function boundedHunkDiffs(path: string, before: string, after: string): RemoteFileDiff[];

package/lib/types/engine.d.ts

@@ -5,10 +5,18 @@
  * (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 { ClusterResult, ExecResult, ProcessInfo, RemoteDirEntry, RemoteEditOutcome, RemoteTextEncoding, RemoteTextWindow, RemoteWriteOutcome, ServiceInfo, TestResult, TransferProgress, WinHostSummary } from './protocol.ts';
 import type { HostStore } from './store.ts';
 import { type TransferChannel } from './smb.ts';
 import { ConsoleSession } from './engine/console.ts';
+/** Longest single line the reader returns before cutting it (characters). */
+export declare const READ_MAX_LINE_LENGTH = 2000;
+/** Lines the reader returns when the caller does not choose a page size. */
+export declare const READ_DEFAULT_LIMIT = 2000;
+/** Most lines the reader will return in one call. */
+export declare const READ_MAX_LIMIT = 5000;
+/** Byte budget for one read window; keeps the envelope well under the transport limit. */
+export declare const READ_MAX_BYTES: number;
 /** The engine. One instance per plugin apply; dispose() clears nothing pooled (WinRM is per-call HTTP). */
 export declare class WinRmEngine {
     readonly store: HostStore;
@@ -39,6 +47,48 @@ export declare class WinRmEngine {
     killProcess(alias: string, id: number): Promise<void>;
     /** List a remote directory. */
     ls(alias: string, dir: string): Promise<RemoteDirEntry[]>;
+    /**
+     * 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.
+     */
+    readFile(alias: string, remotePath: string, offset: number, limit: number): Promise<RemoteTextWindow>;
+    /**
+     * 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.
+     */
+    writeFile(alias: string, remotePath: string, content: string, encoding: RemoteTextEncoding): Promise<RemoteWriteOutcome>;
+    /**
+     * 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.
+     */
+    editFile(alias: string, remotePath: string, oldString: string, newString: string, replaceAll: boolean): Promise<RemoteEditOutcome>;
     /** Upload one local file to a remote path. Defaults to SMB with WinRM fallback. */
     upload(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, channel?: TransferChannel): Promise<{
         bytes: number;

package/lib/types/index.d.ts

@@ -3,8 +3,9 @@
  * execution with a UTF-8 envelope, streaming console, service/process
  * 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
+ * (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_read,
+ * winrm_write, winrm_edit, 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.
  *
@@ -34,7 +35,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\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";
+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_read/winrm_write/winrm_edit \u8FDC\u7A0B\u6587\u672C\u6587\u4EF6\u8BFB\u5199\uFF08\u6309\u884C\u5206\u9875\u3001\u7F16\u7801\u611F\u77E5\u3001\u7CBE\u786E\u4E32\u66FF\u6362\uFF0C\u4F5C\u7528\u4E8E\u8FDC\u7AEF\u4E3B\u673A\u800C\u975E\u672C\u673A\uFF0C\u672C\u673A\u6587\u4EF6\u4ECD\u7528 read/write/edit\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

@@ -108,6 +108,70 @@ 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;
+/**
+ * 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.
+ */
+export declare function psReadTextWindow(p: string, offset: number, limit: number, maxLineLength: number, maxBytes: number): string;
+/**
+ * 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.
+ */
+export declare function psEditText(p: string, oldB64: string, newB64: string, replaceAll: boolean, basisMaxBytes?: number): string;
+/**
+ * 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.
+ */
+export declare function psReadTextBasis(p: string, maxBytes: number): 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. */

package/lib/types/protocol.d.ts

@@ -88,6 +88,60 @@ export interface RemoteDirEntry {
     size: number;
     mtimeMs: number;
 }
+/** One numbered line of a remote text file. */
+export interface RemoteTextLine {
+    /** 1-based line number within the remote file. */
+    number: number;
+    /** Line text without its terminator; over-long lines are cut and annotated. */
+    text: string;
+}
+/** Result of reading a bounded window of a remote text file. */
+export interface RemoteTextWindow {
+    path: string;
+    /** 1-based line number of the first returned line. */
+    offset: number;
+    lines: RemoteTextLine[];
+    /** Lines in the whole file, so the caller can page. */
+    totalLines: number;
+    /** Detected encoding: `utf8`, `utf8bom`, `utf16le` or `utf16be`. */
+    encoding: string;
+    /** True when the window stopped at the byte budget instead of at `limit`. */
+    truncatedByBytes: boolean;
+    /** Lines whose text was cut at the per-line cap and annotated in `lines`. */
+    truncatedLines: number;
+}
+/** Text encodings the writer can emit. */
+export type RemoteTextEncoding = 'utf8' | 'utf8bom' | 'utf16le';
+/** Result of writing a remote text file. */
+export interface RemoteWriteOutcome {
+    path: string;
+    /** `create` when the path was absent, `update` when it was overwritten. */
+    operation: 'create' | 'update';
+    bytes: number;
+    encoding: RemoteTextEncoding;
+    /**
+     * Previous file text, or `null` for a create and for a file too large to
+     * serve as a diff basis. Only the presentation layer reads it.
+     */
+    before: string | null;
+    /** Text after the write, on the same basis as {@link RemoteWriteOutcome.before}. */
+    after: string;
+}
+/** Result of an in-place remote text edit. */
+export interface RemoteEditOutcome {
+    path: string;
+    /** Encoding the file already had, preserved across the edit. */
+    encoding: string;
+    replacements: number;
+    size: number;
+    /**
+     * File text before the edit, or `null` when the file was too large to serve
+     * as a diff basis. Only the presentation layer reads it.
+     */
+    before: string | null;
+    /** Text after the edit, on the same basis as {@link RemoteEditOutcome.before}. */
+    after: string | null;
+}
 /** One server entry in a cluster run. */
 export interface ClusterResult {
     alias: string;

package/lib/types/tools.d.ts

@@ -3,7 +3,7 @@
  * the same engine the web UI uses, so a host configured in the GUI is
  * immediately operable by any agent, and vice versa.
  */
-import type { WinRmEngine } from './engine.ts';
+import { type WinRmEngine } from './engine.ts';
 /** The host-list tool. */
 export declare function winrmListTool(engine: WinRmEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
 /** The command-execution tool (PowerShell). */
@@ -18,3 +18,9 @@ export declare function winrmUploadTool(engine: WinRmEngine): import("@deepseek-
 export declare function winrmDownloadTool(engine: WinRmEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
 /** The cluster tool. */
 export declare function winrmClusterTool(engine: WinRmEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The remote read tool: a line-numbered window of a text file on the target. */
+export declare function winrmReadTool(engine: WinRmEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The remote write tool: replace a whole text file on the target. */
+export declare function winrmWriteTool(engine: WinRmEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The remote edit tool: replace an exact string inside a file on the target. */
+export declare function winrmEditTool(engine: WinRmEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;

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 / 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",
+  "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 / remote text read-write-edit / streamed file transfer / cluster execution, plus agent tools (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_read, winrm_write, winrm_edit, 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.4.0",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {
@@ -34,7 +34,8 @@
         "@deepseek-ai/dsh-client-ui-renderer",
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-layout",
-        "@deepseek-ai/dsh-client-ui-sidebar"
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-tool"
       ],
       "platform": "web"
     }
@@ -56,9 +57,11 @@
     "@deepseek-ai/cordis-plugin-loader": "^1.0.5",
     "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-client-ui-layout": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-ui-renderer": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-client-ui-sidebar": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-tool": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
@@ -79,8 +82,9 @@
     "lib/**/*.d.ts",
     "src",
     "cordis.patch.yml",
+    "docs/screenshots/*.png",
     "README.md",
-    "README.zh.md",
+    "README.en.md",
     "RELEASING.md",
     "scripts"
   ],

package/scripts/verify-live.mts

@@ -6,6 +6,7 @@
 // Run from the repo root so `winrm-client` resolves:
 //   node --experimental-strip-types scripts/verify-live.mts
 import { HostStore } from '../src/store.ts'
+import { WinRmEngine } from '../src/engine.ts'
 import { connOf, runScript, TRANSFER_CHUNK, uploadBuffer, downloadChunks, remoteFileSize } from '../src/engine/client.ts'
 import { psWriteChunk, psReadChunk, psFileSize } from '../src/powershell.ts'
 
@@ -106,6 +107,121 @@ console.log('=== upload/download round trip ===')
   await runScript(conn, `Remove-Item -LiteralPath 'C:\\temp\\dsh-winrm-verify' -Recurse -Force -ErrorAction SilentlyContinue`, { timeoutMs: 60_000 })
 }
 
+// Remote text read/write/edit: the three tools that act on the target's files
+// rather than on the host's. Round-trips through the real encoding detection.
+console.log('=== remote text read/write/edit ===')
+{
+  const engine = new WinRmEngine(store)
+  const dir = 'C:\\temp\\dsh-winrm-verify-text'
+  const alias = entry.alias
+  const body = ['alpha', '中文行 ✓', '', 'beta alpha', 'omega'].join('\r\n') + '\r\n'
+
+  const created = await engine.writeFile(alias, `${dir}\\utf8.txt`, body, 'utf8')
+  const createOk = created.operation === 'create' && created.bytes === Buffer.byteLength(body, 'utf8')
+  if (!createOk) bad++
+  console.log(`${createOk ? 'ok  ' : 'BAD '} write create utf8: op=${created.operation} bytes=${created.bytes}`)
+
+  const updated = await engine.writeFile(alias, `${dir}\\utf8.txt`, body, 'utf8')
+  const updateOk = updated.operation === 'update'
+  if (!updateOk) bad++
+  console.log(`${updateOk ? 'ok  ' : 'BAD '} write update utf8: op=${updated.operation}`)
+
+  const window = await engine.readFile(alias, `${dir}\\utf8.txt`, 1, 100)
+  const readOk = window.totalLines === 5
+    && window.encoding === 'utf8'
+    && window.lines[0]?.text === 'alpha'
+    && window.lines[1]?.text === '中文行 ✓'
+    && window.lines[2]?.text === ''
+    && window.lines[4]?.text === 'omega'
+  if (!readOk) bad++
+  console.log(`${readOk ? 'ok  ' : 'BAD '} read whole: total=${window.totalLines} enc=${window.encoding} lines=${JSON.stringify(window.lines.map(l => l.text))}`)
+
+  // Paging must start where the caller asked, or a model paging a log would
+  // silently re-read the top forever.
+  const tail = await engine.readFile(alias, `${dir}\\utf8.txt`, 4, 2)
+  const pageOk = tail.lines.length === 2 && tail.lines[0]?.number === 4 && tail.lines[0]?.text === 'beta alpha'
+  if (!pageOk) bad++
+  console.log(`${pageOk ? 'ok  ' : 'BAD '} read page offset=4 limit=2: ${JSON.stringify(tail.lines)}`)
+
+  const edited = await engine.editFile(alias, `${dir}\\utf8.txt`, 'omega', 'OMEGA', false)
+  const editOk = edited.replacements === 1 && edited.encoding === 'utf8'
+  if (!editOk) bad++
+  console.log(`${editOk ? 'ok  ' : 'BAD '} edit single: replacements=${edited.replacements} size=${edited.size}`)
+
+  const afterEdit = await engine.readFile(alias, `${dir}\\utf8.txt`, 1, 100)
+  const persisted = afterEdit.lines[4]?.text === 'OMEGA'
+  if (!persisted) bad++
+  console.log(`${persisted ? 'ok  ' : 'BAD '} edit persisted: line5=${JSON.stringify(afterEdit.lines[4]?.text)}`)
+
+  // `alpha` appears twice, so a single-replacement edit must refuse rather than
+  // guess which one the caller meant.
+  let ambiguous = ''
+  try {
+    await engine.editFile(alias, `${dir}\\utf8.txt`, 'alpha', 'ALPHA', false)
+  } catch (error) {
+    ambiguous = error instanceof Error ? error.message : String(error)
+  }
+  const ambiguousOk = ambiguous.includes('more than once')
+  if (!ambiguousOk) bad++
+  console.log(`${ambiguousOk ? 'ok  ' : 'BAD '} edit refuses ambiguous needle: ${JSON.stringify(ambiguous)}`)
+
+  const all = await engine.editFile(alias, `${dir}\\utf8.txt`, 'alpha', 'ALPHA', true)
+  const allOk = all.replacements === 2
+  if (!allOk) bad++
+  console.log(`${allOk ? 'ok  ' : 'BAD '} edit replaceAll: replacements=${all.replacements}`)
+
+  // A needle that is gone must fail loudly: silently succeeding is how a stale
+  // edit looks successful while changing nothing.
+  let missing = ''
+  try {
+    await engine.editFile(alias, `${dir}\\utf8.txt`, 'not-there-at-all', 'x', false)
+  } catch (error) {
+    missing = error instanceof Error ? error.message : String(error)
+  }
+  const missingOk = missing.includes('was not found')
+  if (!missingOk) bad++
+  console.log(`${missingOk ? 'ok  ' : 'BAD '} edit reports a missing needle: ${JSON.stringify(missing)}`)
+
+  // UTF-16LE with a BOM must come back as UTF-16LE, not as mojibake.
+  const utf16 = await engine.writeFile(alias, `${dir}\\utf16.txt`, '第一行\r\n第二行\r\n', 'utf16le')
+  const utf16Read = await engine.readFile(alias, `${dir}\\utf16.txt`, 1, 10)
+  const utf16Ok = utf16Read.encoding === 'utf16le' && utf16Read.lines[0]?.text === '第一行' && utf16Read.lines[1]?.text === '第二行'
+  if (!utf16Ok) bad++
+  console.log(`${utf16Ok ? 'ok  ' : 'BAD '} utf16le round trip: bytes=${utf16.bytes} enc=${utf16Read.encoding} lines=${JSON.stringify(utf16Read.lines.map(l => l.text))}`)
+
+  // A UTF-8 BOM must be preserved by an edit, or the next reader misdetects it.
+  await engine.writeFile(alias, `${dir}\\bom.txt`, 'one\r\ntwo\r\n', 'utf8bom')
+  const bomEdit = await engine.editFile(alias, `${dir}\\bom.txt`, 'two', 'TWO', false)
+  const bomRead = await engine.readFile(alias, `${dir}\\bom.txt`, 1, 10)
+  const bomOk = bomEdit.encoding === 'utf8bom' && bomRead.encoding === 'utf8bom' && bomRead.lines[1]?.text === 'TWO'
+  if (!bomOk) bad++
+  console.log(`${bomOk ? 'ok  ' : 'BAD '} utf8bom preserved through an edit: edit=${bomEdit.encoding} read=${bomRead.encoding}`)
+
+  // A binary file has no line structure; the reader must say so instead of
+  // returning U+FFFD soup.
+  let binary = ''
+  try {
+    await engine.readFile(alias, 'C:\\Windows\\System32\\notepad.exe', 1, 5)
+  } catch (error) {
+    binary = error instanceof Error ? error.message : String(error)
+  }
+  const binaryOk = binary.length > 0
+  if (!binaryOk) bad++
+  console.log(`${binaryOk ? 'ok  ' : 'BAD '} binary read fails loudly: ${JSON.stringify(binary.slice(0, 120))}`)
+
+  let absent = ''
+  try {
+    await engine.readFile(alias, `${dir}\\nope.txt`, 1, 5)
+  } catch (error) {
+    absent = error instanceof Error ? error.message : String(error)
+  }
+  const absentOk = absent.includes('not found')
+  if (!absentOk) bad++
+  console.log(`${absentOk ? 'ok  ' : 'BAD '} read reports a missing file: ${JSON.stringify(absent)}`)
+
+  await runScript(conn, `Remove-Item -LiteralPath '${dir}' -Recurse -Force -ErrorAction SilentlyContinue`, { timeoutMs: 60_000 })
+}
+
 // Sanity: a script that never reaches the envelope must not claim success.
 {
   const r = await runScript(conn, `Write-Output 'ok'`, { timeoutMs: 60_000 })