dsh-plugin-wsl-env 0.7.5 → 0.8.0

package/lib/workspace-files-route.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Pure builders and parsers for the distro-routed `workspace-files` service —
+ * the GUI file tree and previews for a `\\wsl.localhost\<distro>` workspace,
+ * served from inside the distro instead of Windows-side 9P walks.
+ *
+ * Peer-free by construction (no DSH imports): the service subclass imports
+ * this alongside the shipped `dsh-api-workspace-files` base class, and the
+ * unit tests import it standalone.
+ *
+ * This is a TypeScript source built to `lib/workspace-files-route.js`; edit
+ * THIS file and run `pnpm run build` — the artifact under `lib/` is generated,
+ * and `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/workspace-files-route
+ */
+/**
+ * Translate one path-shaped value into distro coordinates: UNC identities map
+ * onto their Linux paths, drive-letter paths onto their `/mnt/<drive>` mounts,
+ * everything else passes through verbatim.
+ *
+ * @param value - the value to translate.
+ * @returns the distro-side spelling.
+ */
+export declare function distroPath(value: string): string;
+/**
+ * Whether a workspace root belongs to a distro (and therefore routes
+ * distro-side).
+ *
+ * @param workspaceRoot - the scope's workspace root, any coordinate system.
+ * @returns true for a `\\wsl.localhost\<distro>` UNC root.
+ */
+export declare function isDistroWorkspace(workspaceRoot: string): boolean;
+/**
+ * The Linux working path for one request: UNC absolutes map onto their Linux
+ * paths, POSIX absolutes and relative paths join onto the root.
+ *
+ * @param linuxRoot - the workspace root in Linux form.
+ * @param path - the requested path, any coordinate system.
+ * @returns the absolute Linux path.
+ */
+export declare function linuxJoin(linuxRoot: string, path: string): string;
+/**
+ * The record invocation for one path: line 1 is the no-follow kind (the
+ * upstream lstat gate), line 2 the follow-stat fields (the upstream final
+ * stat), tab-joined.
+ *
+ * @param file - absolute Linux path.
+ * @returns the agent argv.
+ */
+export declare function statRecordArgv(file: string): string[];
+/**
+ * Parse one stat record (kind + follow fields, tab-joined).
+ *
+ * @param line - the record line.
+ * @returns the upstream kind spelling, the byte size, and the synthesized
+ *   opaque version.
+ */
+export declare function parseStatRecord(line: string | Buffer): {
+    kind: string;
+    type: string;
+    size: number;
+    version: string;
+};
+/**
+ * Map a `stat` kind onto the wire's kind token.
+ *
+ * @param kind - the `stat -c %F` spelling.
+ * @returns the wire kind token.
+ */
+export declare function wireKind(kind: string): string;
+/**
+ * The read invocation for one line-paged text read: the stat record rides
+ * stderr (the caller builds the stat half of the response), the page rides
+ * stdout — one line beyond the page, so EOF is decidable from the yield.
+ * `$1` is the file, `$2` the 1-based first line, `$3` the line count.
+ *
+ * @param file - absolute Linux path.
+ * @param offset - first line to return (1-based).
+ * @param limit - maximum lines to return.
+ * @returns the agent argv.
+ */
+export declare function pageArgv(file: string, offset: number, limit: number): string[];
+/**
+ * The byte-window invocation: the stat record rides stderr, the window rides
+ * stdout. `$1` is the file, `$2` the byte offset, `$3` the byte count.
+ *
+ * @param file - absolute Linux path.
+ * @param offset - byte offset (0-based).
+ * @param length - byte count.
+ * @returns the agent argv.
+ */
+export declare function bytesArgv(file: string, offset: number, length: number): string[];
+/**
+ * Parse the stat record a read or byte-window relayed on stderr.
+ *
+ * @param stderr - the relay's raw stderr.
+ * @returns the parsed stat record, or undefined when stderr carries none.
+ */
+export declare function parseStatRecordFromStderr(stderr: string | Buffer): {
+    kind: string;
+    type: string;
+    size: number;
+    version: string;
+} | undefined;
+/**
+ * The listing invocation for one directory: resolve the final component
+ * through symlinks, refuse paths outside the root and non-directories, then
+ * list one more entry than the cap so truncation is decidable from the yield.
+ * `-L` matches the upstream child semantics (a symlink to a directory lists
+ * as a directory, a broken link drops out); `-p` marks directories with the
+ * trailing `/` the parser keys on.
+ *
+ * @param linuxRoot - the workspace root in Linux form (containment boundary).
+ * @param linuxDir - the directory to list.
+ * @param maxEntries - the caller's entry cap.
+ * @returns the agent argv.
+ */
+export declare function listDistroArgv(linuxRoot: string, linuxDir: string, maxEntries: number): string[];
+/**
+ * Parse one capped `ls -1ALp` listing into wire entries.
+ *
+ * @param stdout - the listing's raw stdout.
+ * @param maxEntries - the entry cap the caller configured.
+ * @returns at most `maxEntries` entries and whether the level had more.
+ */
+export declare function parseDirListing(stdout: string | Buffer, maxEntries: number): {
+    entries: Array<{
+        name: string;
+        type: "file" | "directory";
+    }>;
+    truncated: boolean;
+};

package/lib/workspace-files-route.js

@@ -7,11 +7,13 @@
  * this alongside the shipped `dsh-api-workspace-files` base class, and the
  * unit tests import it standalone.
  *
+ * This is a TypeScript source built to `lib/workspace-files-route.js`; edit
+ * THIS file and run `pnpm run build` — the artifact under `lib/` is generated,
+ * and `pnpm test` fails when it drifts.
+ *
  * @module dsh-plugin-wsl/workspace-files-route
  */
-
 import { isWslUnc, uncToPosix, windowsToLinuxMount } from "./paths.js";
-
 /**
  * Translate one path-shaped value into distro coordinates: UNC identities map
  * onto their Linux paths, drive-letter paths onto their `/mnt/<drive>` mounts,
@@ -21,15 +23,15 @@ import { isWslUnc, uncToPosix, windowsToLinuxMount } from "./paths.js";
  * @returns the distro-side spelling.
  */
 export function distroPath(value) {
-  if (typeof value !== "string") return value;
-  if (isWslUnc(value)) {
-    const parsed = uncToPosix(value);
-    return parsed === undefined ? value : parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
-  }
-  const mounted = windowsToLinuxMount(value);
-  return mounted === undefined ? value : mounted;
+    if (typeof value !== "string")
+        return value;
+    if (isWslUnc(value)) {
+        const parsed = uncToPosix(value);
+        return parsed === undefined ? value : parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+    }
+    const mounted = windowsToLinuxMount(value);
+    return mounted === undefined ? value : mounted;
 }
-
 /**
  * Whether a workspace root belongs to a distro (and therefore routes
  * distro-side).
@@ -38,9 +40,8 @@ export function distroPath(value) {
  * @returns true for a `\\wsl.localhost\<distro>` UNC root.
  */
 export function isDistroWorkspace(workspaceRoot) {
-  return isWslUnc(workspaceRoot);
+    return isWslUnc(workspaceRoot);
 }
-
 /**
  * The Linux working path for one request: UNC absolutes map onto their Linux
  * paths, POSIX absolutes and relative paths join onto the root.
@@ -50,21 +51,19 @@ export function isDistroWorkspace(workspaceRoot) {
  * @returns the absolute Linux path.
  */
 export function linuxJoin(linuxRoot, path) {
-  // The UNC check runs on the RAW spelling: the backslash-to-slash rewrite
-  // below would leave `//wsl.localhost/...`, which the identity regex cannot
-  // see.
-  const parsed = uncToPosix(path);
-  if (parsed !== undefined) return parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
-  const text = String(path).replaceAll("\\", "/");
-  if (text.startsWith("/")) return text.length > 1 ? text.replace(/\/+$/, "") : "/";
-  const base = linuxRoot === "/" ? "" : linuxRoot;
-  const joined = text.length === 0 ? base : `${base}/${text}`.replace(/\/\.(?=\/|$)/gu, "");
-  return joined.length === 0 ? "/" : joined;
+    // The UNC check runs on the RAW spelling: the backslash-to-slash rewrite
+    // below would leave `//wsl.localhost/...`, which the identity regex cannot
+    // see.
+    const parsed = uncToPosix(path);
+    if (parsed !== undefined)
+        return parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+    const text = String(path).replaceAll("\\", "/");
+    if (text.startsWith("/"))
+        return text.length > 1 ? text.replace(/\/+$/, "") : "/";
+    const base = linuxRoot === "/" ? "" : linuxRoot;
+    const joined = text.length === 0 ? base : `${base}/${text}`.replace(/\/\.(?=\/|$)/gu, "");
+    return joined.length === 0 ? "/" : joined;
 }
-
-/** The `stat` format string: kind, size, device, inode, mtimes — tab-joined. */
-const STAT_FORMAT = "%F\t%s\t%D\t%i\t%Y\t%Z";
-
 /**
  * The record invocation for one path: line 1 is the no-follow kind (the
  * upstream lstat gate), line 2 the follow-stat fields (the upstream final
@@ -74,14 +73,13 @@ const STAT_FORMAT = "%F\t%s\t%D\t%i\t%Y\t%Z";
  * @returns the agent argv.
  */
 export function statRecordArgv(file) {
-  const script = [
-    'k=$(stat -c %F -- "$1") || exit 2',
-    's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
-    "printf '%s\\t%s\\n' \"$k\" \"$s\"",
-  ].join("\n");
-  return ["sh", "-c", script, "sh", file];
+    const script = [
+        'k=$(stat -c %F -- "$1") || exit 2',
+        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
+        "printf '%s\\t%s\\n' \"$k\" \"$s\"",
+    ].join("\n");
+    return ["sh", "-c", script, "sh", file];
 }
-
 /**
  * Parse one stat record (kind + follow fields, tab-joined).
  *
@@ -90,15 +88,14 @@ export function statRecordArgv(file) {
  *   opaque version.
  */
 export function parseStatRecord(line) {
-  const [kind, size, dev, ino, mtime, ctime] = String(line).trim().split("\t");
-  return {
-    kind,
-    type: wireKind(kind),
-    size: Number(size),
-    version: `${dev}:${ino}:${size}:${mtime}:${ctime}`,
-  };
+    const [kind, size, dev, ino, mtime, ctime] = String(line).trim().split("\t");
+    return {
+        kind,
+        type: wireKind(kind),
+        size: Number(size),
+        version: `${dev}:${ino}:${size}:${mtime}:${ctime}`,
+    };
 }
-
 /**
  * Map a `stat` kind onto the wire's kind token.
  *
@@ -106,10 +103,9 @@ export function parseStatRecord(line) {
  * @returns the wire kind token.
  */
 export function wireKind(kind) {
-  const mapped = { "regular file": "file", directory: "directory", "symbolic link": "symlink" };
-  return mapped[kind] ?? kind;
+    const mapped = { "regular file": "file", directory: "directory", "symbolic link": "symlink" };
+    return mapped[kind] ?? kind;
 }
-
 /**
  * The read invocation for one line-paged text read: the stat record rides
  * stderr (the caller builds the stat half of the response), the page rides
@@ -122,15 +118,14 @@ export function wireKind(kind) {
  * @returns the agent argv.
  */
 export function pageArgv(file, offset, limit) {
-  const script = [
-    'k=$(stat -c %F -- "$1") || exit 2',
-    's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
-    "printf '%s\\t%s\\n' \"$k\" \"$s\" >&2",
-    'sed -n "${2},$(( $2 + $3 ))p" -- "$1"',
-  ].join("\n");
-  return ["sh", "-c", script, "sh", file, String(offset), String(limit)];
+    const script = [
+        'k=$(stat -c %F -- "$1") || exit 2',
+        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
+        "printf '%s\\t%s\\n' \"$k\" \"$s\" >&2",
+        'sed -n "${2},$(( $2 + $3 ))p" -- "$1"',
+    ].join("\n");
+    return ["sh", "-c", script, "sh", file, String(offset), String(limit)];
 }
-
 /**
  * The byte-window invocation: the stat record rides stderr, the window rides
  * stdout. `$1` is the file, `$2` the byte offset, `$3` the byte count.
@@ -141,14 +136,13 @@ export function pageArgv(file, offset, limit) {
  * @returns the agent argv.
  */
 export function bytesArgv(file, offset, length) {
-  const script = [
-    's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
-    "printf '%s\\n' \"$s\" >&2",
-    'tail -c "+$(( $2 + 1 ))" -- "$1" | head -c "$3"',
-  ].join("\n");
-  return ["sh", "-c", script, "sh", file, String(offset), String(length)];
+    const script = [
+        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
+        "printf '%s\\n' \"$s\" >&2",
+        'tail -c "+$(( $2 + 1 ))" -- "$1" | head -c "$3"',
+    ].join("\n");
+    return ["sh", "-c", script, "sh", file, String(offset), String(length)];
 }
-
 /**
  * Parse the stat record a read or byte-window relayed on stderr.
  *
@@ -156,12 +150,11 @@ export function bytesArgv(file, offset, length) {
  * @returns the parsed stat record, or undefined when stderr carries none.
  */
 export function parseStatRecordFromStderr(stderr) {
-  const line = String(stderr)
-    .split("\n")
-    .find((candidate) => candidate.includes("\t"));
-  return line === undefined ? undefined : parseStatRecord(line);
+    const line = String(stderr)
+        .split("\n")
+        .find((candidate) => candidate.includes("\t"));
+    return line === undefined ? undefined : parseStatRecord(line);
 }
-
 /**
  * The listing invocation for one directory: resolve the final component
  * through symlinks, refuse paths outside the root and non-directories, then
@@ -176,16 +169,15 @@ export function parseStatRecordFromStderr(stderr) {
  * @returns the agent argv.
  */
 export function listDistroArgv(linuxRoot, linuxDir, maxEntries) {
-  const script = [
-    "root=$1 dir=$2 max=$3",
-    'real=$(realpath -L -- "$dir") || exit 2',
-    'case "$real" in "$root") ;; "$root"/*) ;; *) echo "OUTSIDE:$real" >&2; exit 3;; esac',
-    '[ -d "$real" ] || { echo "NOTDIR:$real" >&2; exit 4; }',
-    'ls -1ALp -- "$real" | head -n "$max"',
-  ].join("\n");
-  return ["sh", "-c", script, "sh", linuxRoot, linuxDir, maxEntries + 1];
+    const script = [
+        "root=$1 dir=$2 max=$3",
+        'real=$(realpath -L -- "$dir") || exit 2',
+        'case "$real" in "$root") ;; "$root"/*) ;; *) echo "OUTSIDE:$real" >&2; exit 3;; esac',
+        '[ -d "$real" ] || { echo "NOTDIR:$real" >&2; exit 4; }',
+        'ls -1ALp -- "$real" | head -n "$max"',
+    ].join("\n");
+    return ["sh", "-c", script, "sh", linuxRoot, linuxDir, String(maxEntries + 1)];
 }
-
 /**
  * Parse one capped `ls -1ALp` listing into wire entries.
  *
@@ -194,12 +186,12 @@ export function listDistroArgv(linuxRoot, linuxDir, maxEntries) {
  * @returns at most `maxEntries` entries and whether the level had more.
  */
 export function parseDirListing(stdout, maxEntries) {
-  const lines = String(stdout).split("\n").filter((line) => line.length > 0);
-  const truncated = lines.length > maxEntries;
-  const entries = lines.slice(0, maxEntries).map((line) => {
-    const directory = line.endsWith("/");
-    const name = directory ? line.slice(0, -1) : line;
-    return { name, type: directory ? "directory" : "file" };
-  });
-  return { entries, truncated };
+    const lines = String(stdout).split("\n").filter((line) => line.length > 0);
+    const truncated = lines.length > maxEntries;
+    const entries = lines.slice(0, maxEntries).map((line) => {
+        const directory = line.endsWith("/");
+        const name = directory ? line.slice(0, -1) : line;
+        return { name, type: directory ? "directory" : "file" };
+    });
+    return { entries, truncated };
 }

package/lib/workspace-files-wsl.d.ts

@@ -0,0 +1,257 @@
+/**
+ * The distro-routed `workspace-files` service: the GUI file tree and previews
+ * for a `\\wsl.localhost\<distro>` workspace are served from inside the distro
+ * through the resident agent, instead of Windows-side 9P walks.
+ *
+ * ## Route predicate
+ *
+ * Every override checks `scope.workspaceRoot` — a distro UNC routes
+ * distro-side, a drive path calls `super` (host native, unchanged).
+ * `changes` (the watch stream) always delegates to `super`: its feed rides
+ * `ctx.fs.watch`, whose behaviour is today's on both workspace kinds.
+ *
+ * ## What the distro side reproduces
+ *
+ * The wire shapes of `dsh-api-workspace-files`: listings capped with a
+ * `truncated` flag, stats of `{absolutePath, version, bytes?}`, line-paged
+ * text with NUL and UTF-8 refusal and the byte-cap error, and byte windows
+ * with EOF markers. Versions are synthesized from `stat` fields — opaque to
+ * the client, which only compares them. `absolutePath` is synthesized in the
+ * UNC form so the GUI's path display stays what it was on the host fs. Read
+ * refuses a final-component symlink exactly like the upstream `locateFile`
+ * lstat gate does; `list` follows one (matching its own symlink-through
+ * rule).
+ *
+ * The distro operations are standalone functions over an injected runner, so
+ * they are unit-testable with a fake agent; the class methods are thin
+ * coordinate guards around them.
+ *
+ * This is a TypeScript source built to `lib/workspace-files-wsl.js`; edit THIS
+ * file and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/workspace-files-wsl
+ */
+import { WorkspaceFiles } from "@deepseek-ai/dsh-api-workspace-files";
+import type { WorkspaceByteReadOptions, WorkspaceDirectoryListing, WorkspaceFileBytes, WorkspaceFileRange, WorkspaceFileScope, WorkspaceFileStat, WorkspaceFileText } from "@deepseek-ai/dsh-api-workspace-files";
+import type { WslAgent } from "./agent.js";
+/**
+ * This variant row's own validated config. The base class keeps `config`
+ * private and its public seam exposes no configuration channel, while the
+ * distro branch enforces the caps the row carries — so the read goes through
+ * this one documented cast. The keys mirror this row's `config` in
+ * `cordis.patch.yml`.
+ */
+export interface WorkspaceFilesWslConfig {
+    /** The directory listing's entry cap. */
+    maxEntries: number;
+    /** The text read's line cap. */
+    maxLines: number;
+    /** The text read's byte cap. */
+    maxBytes: number;
+    /** The byte read's full-file cap. */
+    maxFileBytes: number;
+}
+/**
+ * One parsed distro directory listing. The route parser's own inference
+ * widens the entry kind to `string`; the relay only ever emits the two wire
+ * tokens below, and this is what the cast at the parse boundary restores.
+ */
+export interface DistroListing {
+    /** The level's child entries. */
+    entries: Array<{
+        name: string;
+        type: "file" | "directory";
+        size?: number;
+    }>;
+    /** Whether the level had more entries than the cap. */
+    truncated: boolean;
+}
+/**
+ * List one distro directory through the runner.
+ *
+ * The agent argv confines the directory under the workspace root, refuses
+ * non-directories, and emits one line per child — a trailing `/` marks a
+ * directory (symlinks resolve through, broken links drop out, matching the
+ * upstream child semantics).
+ *
+ * @param object - the listing's inputs.
+ * @returns the listing, with `path` relative to the workspace root (empty for it).
+ */
+export declare function distroList({ runner, distro, linuxRoot, path, maxEntries, signal }: {
+    /** The agent-like runner (`exec`). */
+    runner: WslAgent;
+    /** The distro name. */
+    distro: string;
+    /** The workspace root in Linux form. */
+    linuxRoot: string;
+    /** The requested directory, any coordinate system. */
+    path: string;
+    /** The entry cap. */
+    maxEntries: number;
+    /** Caller cancellation. */
+    signal?: AbortSignal;
+}): Promise<{
+    path: string;
+    entries: Array<{
+        name: string;
+        type: "file" | "directory";
+        size?: number;
+    }>;
+    truncated: boolean;
+}>;
+/**
+ * Stat one distro path through the runner.
+ *
+ * @param object - the stat's inputs.
+ * @returns the wire stat row.
+ */
+export declare function distroStat({ runner, distro, linuxRoot, path, distroWorkspaceRoot, signal }: {
+    /** The agent-like runner (`exec`). */
+    runner: WslAgent;
+    /** The distro name. */
+    distro: string;
+    /** The workspace root in Linux form. */
+    linuxRoot: string;
+    /** The requested path, any coordinate system. */
+    path: string;
+    /** The UNC workspace root, for the absolutePath display form. */
+    distroWorkspaceRoot: string;
+    /** Caller cancellation. */
+    signal?: AbortSignal;
+}): Promise<{
+    absolutePath: string;
+    version: string;
+    bytes?: number;
+}>;
+/**
+ * Read one line-paged UTF-8 window through the runner, mirroring the
+ * upstream `cutPage` semantics: a NUL byte marks the page binary, a page
+ * above the byte cap is refused (never shortened), and `eof` is false exactly
+ * when a character exists past the page.
+ *
+ * @param object - the read's inputs.
+ * @returns the wire text page.
+ */
+export declare function distroRead({ runner, distro, linuxRoot, path, offset, limit, maxBytes, distroWorkspaceRoot, signal }: {
+    /** The agent-like runner (`exec`). */
+    runner: WslAgent;
+    /** The distro name. */
+    distro: string;
+    /** The workspace root in Linux form. */
+    linuxRoot: string;
+    /** The requested path, any coordinate system. */
+    path: string;
+    /** First line to return (1-based). */
+    offset: number;
+    /** Maximum lines to return. */
+    limit: number;
+    /** The page's byte cap. */
+    maxBytes: number;
+    /** The UNC workspace root, for the absolutePath display form. */
+    distroWorkspaceRoot: string;
+    /** Caller cancellation. */
+    signal?: AbortSignal;
+}): Promise<{
+    absolutePath: string;
+    version: string;
+    bytes?: number;
+    offset: number;
+    text: string;
+    lines: number;
+    eof: boolean;
+}>;
+/**
+ * Read one byte window (or the capped whole file) through the runner.
+ *
+ * @param object - the read's inputs.
+ * @returns the wire byte read.
+ */
+export declare function distroReadBytes({ runner, distro, linuxRoot, path, offset, length, maxBytes, maxFileBytes, distroWorkspaceRoot, signal }: {
+    /** The agent-like runner (`exec`). */
+    runner: WslAgent;
+    /** The distro name. */
+    distro: string;
+    /** The workspace root in Linux form. */
+    linuxRoot: string;
+    /** The requested path, any coordinate system. */
+    path: string;
+    /** Byte offset (0-based). */
+    offset: number | undefined;
+    /** Byte count. */
+    length: number | undefined;
+    /** The window's inclusive byte cap; undefined leaves the window uncapped. */
+    maxBytes?: number | undefined;
+    /** The complete-file cap. */
+    maxFileBytes: number;
+    /** The UNC workspace root, for the absolutePath display form. */
+    distroWorkspaceRoot: string;
+    /** Caller cancellation. */
+    signal?: AbortSignal;
+}): Promise<{
+    absolutePath: string;
+    version: string;
+    bytes?: number;
+    offset: number;
+    data: Uint8Array;
+    eof: boolean;
+}>;
+/**
+ * The distro-routed `workspace-files` service.
+ */
+export declare class WorkspaceFilesWsl extends WorkspaceFiles {
+    static Config: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/dsh-api-workspace-files").Config>;
+    /**
+     * The agent runner for one distro; a hook tests substitute.
+     *
+     * @param distro - the distro name.
+     * @returns the agent runner.
+     */
+    runnerFor(distro: string): WslAgent;
+    /**
+     * The distro coordinates of one workspace scope.
+     *
+     * @param workspaceRoot - the scope's workspace root.
+     * @returns the distro and its workspace root in Linux form.
+     */
+    coords(workspaceRoot: string): {
+        distro: string;
+        linuxRoot: string;
+    };
+    /**
+     * List one workspace directory; distro UNC roots list inside the distro.
+     *
+     * @param workspaceFileScope - the Session's file scope.
+     * @param path - the directory to list.
+     * @param signal - caller cancellation.
+     */
+    list(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>;
+    /**
+     * Stat one workspace file; distro UNC roots stat inside the distro.
+     *
+     * @param workspaceFileScope - the Session's file scope.
+     * @param path - the file to stat.
+     * @param signal - caller cancellation.
+     */
+    stat(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>;
+    /**
+     * Read one line page; distro UNC roots read inside the distro.
+     *
+     * @param workspaceFileScope - the Session's file scope.
+     * @param path - the file to read.
+     * @param range - the line window.
+     * @param signal - caller cancellation.
+     */
+    read(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>;
+    /**
+     * Read one byte window or the complete file; distro UNC roots read inside
+     * the distro.
+     *
+     * @param workspaceFileScope - the Session's file scope.
+     * @param path - the file to read.
+     * @param options - the byte window.
+     * @param signal - caller cancellation.
+     */
+    readBytes(workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal): Promise<WorkspaceFileBytes>;
+}
+export default WorkspaceFilesWsl;