@prettier-ai/dsh-host-directory-picker-browse 0.1.2-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/host/directory-picker-browse/README.md
+README.md: 986504a48da5b1ea28c174168eec41e40bb77e4e
+README.zh.md: 54a722bdad2d88e6cadc6f39c74f479851197351

package/README.md

@@ -0,0 +1,122 @@
+---
+description: "In-app browsing backend of the directory-picker seam: one-level directory listing and child-directory creation for the web GUI host, serving remote clients too."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-host-directory-picker-browse
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Users who cannot reach an OS chooser still pick a workspace directory through `dsh-host-directory-picker-browse`: it provides one-level directory listing and child-directory creation over Node's standard library, and nothing renders on the host display — so it serves the remote clients the native backend cannot reach. Listings return directories only, name-sorted, with symlink-to-directory following and a host-owned `hidden` flag; creation is non-recursive and validates a single path segment. One composition row also fills the workspace flow's directory holes with the in-app **Select Workspace Directory** dialog.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Compose this backend when a workspace directory must be chosen without an OS chooser — remote browsers, SSH-forwarded sessions, or unattended hosts. The workspace flow drives `directoryPicker/list` and `directoryPicker/createDirectory`; both primitives answer from the host filesystem.
+
+### Listing a directory
+
+`list(path?)` returns one directory level: name-sorted child directories with their absolute paths, a `hidden` flag (dot-prefixed on POSIX), a `home` anchor, and `crumbs` — the root-to-target ancestor chain where every crumb is a jump target and the root is labeled by its full path. An absent path lists the host account's home directory. One call returns at most `maxEntries` rows (config, default 1,000 — the bound GitHub's web UI applies to directory listings), and a cut level reports `truncated: true` so the client can say the level is incomplete. Symlinks to directories are followed; broken and cyclic links are skipped.
+
+### Creating a directory
+
+`createDirectory(path, name)` creates one child directory under an existing parent. It is non-recursive — a missing parent is a real failure, not a level to invent — and rejects anything but a single non-blank path segment (`name` must not contain separators and must not be `.` or `..`).
+
+### Observable failures
+
+Both primitives refuse a path that is not fully qualified — relative forms, and on Windows the rooted drive-less forms (`\foo`, `/foo`) and incomplete UNC prefixes that `isAbsolute` accepts — with `directory-unreadable` or `directory-create-failed`, instead of resolving it under the host process working directory. Creation of an existing child answers `directory-exists`. A caller's `AbortSignal` stops an in-flight scan, so a disconnect or timeout does not leave the scan outliving the caller.
+
+### Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `maxEntries` | `1,000` | Complete-result bound of one listing level; hidden rows count toward it |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-host-directory-picker-browse) is the exhaustive source for every accepted field and its JSDoc.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+### Design concept
+
+The backend streams one directory level through a bounded name-sorted window so memory stays O(maxEntries) no matter how many children the directory holds: a cut level keeps the name-sorted head, hidden rows count against the bound, only windowed candidates are probed, and the level reports `truncated: true`. Window insertion is binary with an O(1) full-window tail rejection, so an oversized level costs O(1) per candidate past the head instead of a window scan.
+
+### The fully-qualified fence
+
+`fullyQualified` rejects any path that does not name one fixed filesystem location regardless of process state: POSIX-absolute on POSIX; on Windows only drive-qualified (`C:\…`) or complete UNC (`\\server\share…`) forms. Rooted drive-less forms and incomplete UNC prefixes pass `isAbsolute` yet still resolve against the process's current drive, so the backend refuses them rather than rebasing a wire value.
+
+### Abort and probing
+
+Every filesystem await races the caller's signal (`raceAbort`), so a stalled network filesystem cannot keep a departed caller's request alive; an abandoned read's late settlement is swallowed. Symlink enterability is decided by a `stat` probe — failure means not enterable — and a windowed broken symlink is not backfilled from beyond the window, because an eviction already marked the level truncated.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `BrowseDirectoryPicker` service: listing, creation, bounded window, error mapping |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; the filesystem is authoritative) |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these when the backend contract is not enough: the seam definition first, then the decision record and the native alternative.
+
+- [Directory-picker seam](../directory-picker/README.md) — the `browse` capability contract and the typed error vocabulary.
+- [Directory-picker capability seam decision](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md) — the policy decisions behind listing and creation.
+- [Native backend](../directory-picker-native/README.md) — the OS-chooser alternative for local operators.
+- [Adaptive chooser](../directory-picker-auto/README.md) — boot-time resolution between the two backends.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-host-directory-picker-browse) — every accepted config field and its source declaration.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the GUI-host picking backend registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define where the browse interaction is incomplete or intentionally unscoped. They are current package constraints, not a task backlog.
+
+- **Windows hidden attribute is not read** — Node dirents do not expose `FILE_ATTRIBUTE_HIDDEN`, so `hidden` means dot-prefixed on every platform until a native probe is worth its cost.
+- **No drive-root enumeration** — on Windows the ancestry stops at the drive root; crossing drives waits for the browser UI's path-entry affordance rather than an enumeration primitive here.
+- **Whole-filesystem scope** — there is no per-deployment browse-root restriction; `workspace.create` accepts arbitrary paths, so a root here would be UX scoping rather than a security boundary.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,122 @@
+---
+description: "目录选择 seam 的应用内浏览后端：为 web GUI 宿主提供单层目录列举与子目录创建，也能服务于远程客户端。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-host-directory-picker-browse
+
+[English](README.md) | 中文
+
+## 概述
+
+无法触达 OS 选择器的用户仍能通过 `dsh-host-directory-picker-browse` 选择工作区目录：它基于 Node 标准库提供单层目录列举与子目录创建，宿主屏幕上不渲染任何东西——因此它能服务原生后端无法触及的远程客户端。列举只返回目录、按名称排序，跟随指向目录的符号链接，并携带宿主判定的 `hidden` 标志；创建不递归，且把名称校验为单个路径段。一行组合配置还会用应用内**选择工作区目录**对话框填满工作区流程的目录扩展位。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当工作区目录必须在没有 OS 选择器的情况下被选中时——远程浏览器、SSH 转发会话或无人值守宿主——组合此后端。工作区流程驱动 `directoryPicker/list` 与 `directoryPicker/createDirectory`；两个原语都从宿主文件系统作答。
+
+### 列举目录
+
+`list(path?)` 返回一个目录层级：按名称排序的子目录及其绝对路径、`hidden` 标志（POSIX 上为点前缀）、`home` 锚点，以及 `crumbs`——从根到目标的祖先链，其中每个 crumb 都是跳转目标，根以完整路径标注。不带路径时列举宿主账户的家目录。单次调用至多返回 `maxEntries` 行（配置项，默认 1,000——GitHub 网页端对目录列举采用的同一上限），被截断的层级会报告 `truncated: true`，供客户端提示层级不完整。指向目录的符号链接会被跟随；断链与循环链接被跳过。
+
+### 创建目录
+
+`createDirectory(path, name)` 在既有父目录下创建一个子目录。它不递归——父目录缺失是真实失败，不是要补造的层级——并且拒绝任何非单个非空白路径段的内容（`name` 不得包含分隔符，也不得为 `.` 或 `..`）。
+
+### 可观察的失败
+
+两个原语都拒绝非完全限定的路径——相对形态，以及 Windows 上 `isAbsolute` 会放行的无盘符有根形态（`\foo`、`/foo`）与不完整的 UNC 前缀——报 `directory-unreadable` 或 `directory-create-failed`，而不是把它解析到宿主进程工作目录之下。创建已存在的子目录回答 `directory-exists`。调用方的 `AbortSignal` 会停止进行中的扫描，因此断连或超时不会让扫描比调用方活得更久。
+
+### 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `maxEntries` | `1,000` | 单个列举层级的完整结果上限；隐藏行计入该上限 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-host-directory-picker-browse)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+### 设计理念
+
+后端把单个目录层级流式送入一个有界、按名排序的窗口，因此无论目录有多少子项，内存都保持 O(maxEntries)：被截断的层级保留按名排序的头部、隐藏行计入上限、只探测窗口内候选，并报告 `truncated: true`。窗口插入为二分查找、满窗尾部单次比较即拒绝，因此超大型层级在头部之后的每个候选都只需 O(1)，而不是窗口扫描。
+
+### 完全限定栅栏
+
+`fullyQualified` 拒绝任何不指向一个与进程状态无关的固定文件系统位置的路径：POSIX 上要求 POSIX 绝对路径；Windows 上只接受盘符限定（`C:\…`）或完整 UNC（`\\server\share…`）形态。无盘符有根形态与不完整 UNC 前缀能通过 `isAbsolute`，却仍会解析到进程的当前盘符，因此后端拒绝它们，而不是重定位一个 wire 值。
+
+### 中止与探测
+
+每个文件系统 await 都与调用方的信号竞争（`raceAbort`），因此停滞的网络文件系统不能让已离开的调用方请求继续存活；被弃读的迟到结算会被吞掉。符号链接的可进入性由 `stat` 探测决定——失败即不可进入——窗口内的断链符号链接不会从窗口外回填，因为发生过驱逐本身已把层级标记为截断。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `BrowseDirectoryPicker` 服务：列举、创建、有界窗口、错误映射 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；文件系统是权威） |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当后端约定不够用时阅读以下内容：先看 seam 定义，再看决策记录与原生替代方案。
+
+- [目录选择 seam](../directory-picker/README.zh.md)——`browse` 能力约定与类型化错误词汇。
+- [目录选择能力 seam 决策](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md)——列举与创建背后的策略裁决。
+- [原生后端](../directory-picker-native/README.zh.md)——面向本地操作者的 OS 选择器替代方案。
+- [自适应选择器](../directory-picker-auto/README.zh.md)——两个后端之间的启动时判定。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-host-directory-picker-browse)——每个受支持配置字段及其源声明。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。GUI 宿主的目录选择后端不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明浏览交互在何处不完整或有意不限定范围。它们是当前包约束，不是任务积压。
+
+- **不读取 Windows 隐藏属性**——Node 的 dirent 不暴露 `FILE_ATTRIBUTE_HIDDEN`，因此在所有平台上 `hidden` 都意味着点前缀，直到原生探测值得付出相应成本为止。
+- **不枚举盘符根**——Windows 上祖先链止于盘符根；跨盘依赖浏览器 UI 的路径输入入口，而不是这里的枚举原语。
+- **全盘可浏览**——没有按部署限定的浏览根；`workspace.create` 接受任意路径，因此这里的根会限定 UX 范围，而不是安全边界。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,234 @@
+import { mkdir, opendir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, posix, resolve, win32 } from "node:path";
+import z from "@prettier-ai/schemastery";
+import { DirectoryPicker, DirectoryPickerError } from "@prettier-ai/dsh-host-directory-picker";
+//#region lib/types/index.js
+/**
+* Browse backend of the directory-picker seam: registers `ctx.directoryPicker`
+* with the `browse` capability — one-level directory listing and child-directory
+* creation over the host filesystem via Node's stdlib (which already carries
+* the per-OS adaptation). Nothing renders on the host display, so this backend
+* serves remote clients the dialog backend cannot. Policy decisions (hidden
+* entries flagged but returned, symlinks followed, whole-filesystem scope) are
+* recorded in the directory-picker seam Agent Note.
+* @module @prettier-ai/dsh-host-directory-picker-browse
+*/
+/**
+* Ancestor chain from the filesystem root to `target` inclusive — the
+* breadcrumb rows of a listing, every one a jump target.
+*/
+function ancestryCrumbs(target) {
+	const crumbs = [];
+	let current = target;
+	for (;;) {
+		const parent = dirname(current);
+		crumbs.unshift({
+			name: parent === current ? current : basename(current),
+			path: current,
+			hidden: false
+		});
+		if (parent === current) return crumbs;
+		current = parent;
+	}
+}
+/**
+* True when the path names one fixed filesystem location regardless of
+* process state: POSIX-absolute on POSIX; on Windows only drive-qualified
+* (`C:\…`) or complete UNC (`\\server\share…`) forms. Rooted drive-less
+* forms (`\foo`, `/foo`) and incomplete UNC prefixes (`\\`, `\\server`)
+* pass `isAbsolute` yet still resolve against the process's current drive.
+* @param path - candidate path.
+* @param platform - replaces `process.platform` for deterministic tests.
+* @returns whether the path is fully qualified on the platform.
+*/
+function fullyQualified(path, platform = process.platform) {
+	return platform === "win32" ? win32.isAbsolute(path) && /^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/]+[^\\/]+)/.test(path) : posix.isAbsolute(path);
+}
+/**
+* Insert a streamed candidate into the name-sorted bounded window, evicting
+* the name-largest candidate when the window exceeds `keep`. Memory over an
+* arbitrarily large level therefore stays O(keep) regardless of how many
+* children the directory holds.
+* @param window - the name-ascending window, mutated in place.
+* @param candidate - the streamed candidate to place.
+* @param keep - the window bound.
+* @returns true when an eviction happened (the level has candidates beyond the window).
+*/
+function boundedInsert(window, candidate, keep) {
+	if (window.length === keep && candidate.name.localeCompare(window[window.length - 1].name) >= 0) return true;
+	let lo = 0;
+	let hi = window.length;
+	while (lo < hi) {
+		const mid = lo + hi >>> 1;
+		if (candidate.name.localeCompare(window[mid].name) < 0) hi = mid;
+		else lo = mid + 1;
+	}
+	window.splice(lo, 0, candidate);
+	if (window.length <= keep) return false;
+	window.pop();
+	return true;
+}
+/**
+* Await `operation`, but reject with the signal's reason the moment it
+* aborts. Node's filesystem reads are not retractable, so the operation
+* itself keeps running against a handle the caller then closes — its late
+* settlement is swallowed here so an abandoned read cannot surface as an
+* unhandled rejection.
+* @param operation - the in-flight filesystem step.
+* @param signal - caller lifetime; absent means plain awaiting.
+* @returns the operation's value.
+*/
+function raceAbort(operation, signal) {
+	if (signal === void 0) return operation;
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			operation.catch(() => {});
+			reject(asError(signal.reason));
+		};
+		if (signal.aborted) {
+			onAbort();
+			return;
+		}
+		signal.addEventListener("abort", onAbort, { once: true });
+		operation.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (reason) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(asError(reason));
+		});
+	});
+}
+/** The thrown value as an Error (wire/abort reasons may be anything). */
+function asError(reason) {
+	return reason instanceof Error ? reason : new Error(String(reason));
+}
+/* v8 ignore start -- a close failure of an abandoned handle has no consumer, and forcing one needs a filesystem torn down mid-request. */
+/** Swallow the close failure of a handle its caller already departed. */
+function swallowCloseFailure() {}
+/* v8 ignore stop */
+/** Message text of an unknown thrown value. */
+function messageOf(error) {
+	/* v8 ignore next -- node:fs rejects with Error instances; the String arm only satisfies the unknown narrowing. */
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* One listing row for a dirent, following symlinks to directories; null for
+* non-directories and broken/cyclic links (skipped silently — the browser
+* shows what can be entered, and a broken link cannot).
+*/
+async function directoryRow(parent, name, isDirectory, isSymbolicLink, signal) {
+	const path = join(parent, name);
+	let enterable = isDirectory;
+	if (!enterable && isSymbolicLink) try {
+		enterable = (await raceAbort(stat(path), signal)).isDirectory();
+	} catch {
+		/* v8 ignore next 2 -- an abort landing mid-probe needs a stalled stat; the per-candidate check in list covers the settled path. */
+		if (signal?.aborted) throw asError(signal.reason);
+		return null;
+	}
+	if (!enterable) return null;
+	return {
+		name,
+		path,
+		hidden: name.startsWith(".")
+	};
+}
+/** The `ctx.directoryPicker` browse implementation (stable capability object per service life). */
+var BrowseDirectoryPicker = class extends DirectoryPicker {
+	config;
+	/**
+	* `maxEntries` bounds the complete listing level a single `list` call may
+	* materialize and put on the wire: at most this many child-directory rows
+	* (hidden rows included), with `truncated` flagging a cut level. The
+	* default follows GitHub's web UI, which truncates directory listings at
+	* 1,000 entries.
+	*/
+	static Config = z.object({ maxEntries: z.natural().min(1).default(1e3) });
+	browseCapability = {
+		kind: "browse",
+		list: (path, signal) => this.list(path, signal),
+		createDirectory: (path, name) => this.createDirectory(path, name)
+	};
+	constructor(ctx, config) {
+		super(ctx);
+		this.config = config;
+	}
+	/**
+	* The browse interaction capability.
+	* @returns the stable `browse` capability object.
+	*/
+	capability() {
+		return this.browseCapability;
+	}
+	async list(path, signal) {
+		const home = homedir();
+		if (path !== void 0 && !fullyQualified(path)) throw new DirectoryPickerError("directory-unreadable", path, `cannot list "${path}": not a fully qualified path`);
+		const target = resolve(path ?? home);
+		const keep = this.config.maxEntries + 1;
+		const window = [];
+		let evicted = false;
+		try {
+			const opening = opendir(target);
+			const level = await raceAbort(opening, signal).catch((error) => {
+				opening.then((dir) => dir.close().catch(swallowCloseFailure), () => {});
+				throw error;
+			});
+			try {
+				for (;;) {
+					const dirent = await raceAbort(level.read(), signal);
+					if (dirent === null) break;
+					if (!dirent.isDirectory() && !dirent.isSymbolicLink()) continue;
+					if (boundedInsert(window, {
+						name: dirent.name,
+						isDirectory: dirent.isDirectory(),
+						isSymbolicLink: dirent.isSymbolicLink()
+					}, keep)) evicted = true;
+				}
+			} finally {
+				const closing = level.close();
+				/* v8 ignore next 3 -- an abort between open and close needs a stalled read; the abandoned-close arm has no observable outcome. */
+				if (signal?.aborted) closing.catch(swallowCloseFailure);
+				else await closing;
+			}
+		} catch (error) {
+			signal?.throwIfAborted();
+			throw new DirectoryPickerError("directory-unreadable", target, `cannot list ${target}: ${messageOf(error)}`);
+		}
+		const entries = [];
+		let truncated = evicted;
+		for (const candidate of window) {
+			signal?.throwIfAborted();
+			const row = await directoryRow(target, candidate.name, candidate.isDirectory, candidate.isSymbolicLink, signal);
+			if (row === null) continue;
+			if (entries.length === this.config.maxEntries) {
+				truncated = true;
+				break;
+			}
+			entries.push(row);
+		}
+		return {
+			path: target,
+			home,
+			crumbs: ancestryCrumbs(target),
+			entries,
+			truncated
+		};
+	}
+	async createDirectory(path, name) {
+		if (!fullyQualified(path)) throw new DirectoryPickerError("directory-create-failed", path, `cannot create under "${path}": not a fully qualified parent path`);
+		const parent = resolve(path);
+		if (name.trim() === "" || name === "." || name === ".." || /[/\\]/.test(name)) throw new DirectoryPickerError("directory-create-failed", join(parent, name), `"${name}" is not a single path segment`);
+		const target = join(parent, name);
+		try {
+			await mkdir(target);
+			return target;
+		} catch (error) {
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST") throw new DirectoryPickerError("directory-exists", target, `${target} already exists`);
+			throw new DirectoryPickerError("directory-create-failed", target, `cannot create ${target}: ${messageOf(error)}`);
+		}
+	}
+};
+//#endregion
+export { boundedInsert, BrowseDirectoryPicker as default, fullyQualified, raceAbort };

package/lib/invariant.js

@@ -0,0 +1,20 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for the browse directory-picker backend.
+* @module @prettier-ai/dsh-host-directory-picker-browse/invariant
+*/
+const PACKAGE_NAME = "@prettier-ai/dsh-host-directory-picker-browse";
+/** Cordis companion plugin name. */
+const name = "host-directory-picker-browse-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** No runtime invariant: each list/create is one stateless filesystem round trip; the filesystem itself is the authoritative state. */
+const install = () => {};
+/**
+* Register the browse directory-picker invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Browse backend of the directory-picker seam: registers `ctx.directoryPicker`
+ * with the `browse` capability — one-level directory listing and child-directory
+ * creation over the host filesystem via Node's stdlib (which already carries
+ * the per-OS adaptation). Nothing renders on the host display, so this backend
+ * serves remote clients the dialog backend cannot. Policy decisions (hidden
+ * entries flagged but returned, symlinks followed, whole-filesystem scope) are
+ * recorded in the directory-picker seam Agent Note.
+ * @module @prettier-ai/dsh-host-directory-picker-browse
+ */
+import type { Context } from '@prettier-ai/cordis';
+import z from '@prettier-ai/schemastery';
+import { DirectoryPicker } from '@prettier-ai/dsh-host-directory-picker';
+import type { DirectoryPickerCapability } from '@prettier-ai/dsh-host-directory-picker';
+/**
+ * True when the path names one fixed filesystem location regardless of
+ * process state: POSIX-absolute on POSIX; on Windows only drive-qualified
+ * (`C:\…`) or complete UNC (`\\server\share…`) forms. Rooted drive-less
+ * forms (`\foo`, `/foo`) and incomplete UNC prefixes (`\\`, `\\server`)
+ * pass `isAbsolute` yet still resolve against the process's current drive.
+ * @param path - candidate path.
+ * @param platform - replaces `process.platform` for deterministic tests.
+ * @returns whether the path is fully qualified on the platform.
+ */
+export declare function fullyQualified(path: string, platform?: NodeJS.Platform): boolean;
+/** One streamed listing candidate: the dirent facts a row needs, nothing else retained. */
+export interface ListingCandidate {
+    /** Base name within the streamed level. */
+    name: string;
+    /** Dirent says directory (no probe needed). */
+    isDirectory: boolean;
+    /** Dirent says symlink (enterability needs a stat probe). */
+    isSymbolicLink: boolean;
+}
+/**
+ * Insert a streamed candidate into the name-sorted bounded window, evicting
+ * the name-largest candidate when the window exceeds `keep`. Memory over an
+ * arbitrarily large level therefore stays O(keep) regardless of how many
+ * children the directory holds.
+ * @param window - the name-ascending window, mutated in place.
+ * @param candidate - the streamed candidate to place.
+ * @param keep - the window bound.
+ * @returns true when an eviction happened (the level has candidates beyond the window).
+ */
+export declare function boundedInsert(window: ListingCandidate[], candidate: ListingCandidate, keep: number): boolean;
+/**
+ * Await `operation`, but reject with the signal's reason the moment it
+ * aborts. Node's filesystem reads are not retractable, so the operation
+ * itself keeps running against a handle the caller then closes — its late
+ * settlement is swallowed here so an abandoned read cannot surface as an
+ * unhandled rejection.
+ * @param operation - the in-flight filesystem step.
+ * @param signal - caller lifetime; absent means plain awaiting.
+ * @returns the operation's value.
+ */
+export declare function raceAbort<T>(operation: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+/** Validated plugin configuration. */
+export interface Config {
+    /** Complete-result bound of one listing level; see {@link BrowseDirectoryPicker.Config}. */
+    maxEntries: number;
+}
+/** The `ctx.directoryPicker` browse implementation (stable capability object per service life). */
+export default class BrowseDirectoryPicker extends DirectoryPicker {
+    private readonly config;
+    /**
+     * `maxEntries` bounds the complete listing level a single `list` call may
+     * materialize and put on the wire: at most this many child-directory rows
+     * (hidden rows included), with `truncated` flagging a cut level. The
+     * default follows GitHub's web UI, which truncates directory listings at
+     * 1,000 entries.
+     */
+    static Config: z<Config>;
+    private readonly browseCapability;
+    constructor(ctx: Context, config: Config);
+    /**
+     * The browse interaction capability.
+     * @returns the stable `browse` capability object.
+     */
+    capability(): DirectoryPickerCapability;
+    private list;
+    private createDirectory;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for the browse directory-picker backend.
+ * @module @prettier-ai/dsh-host-directory-picker-browse/invariant
+ */
+import type { Context } from '@prettier-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "host-directory-picker-browse-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the browse directory-picker invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@prettier-ai/dsh-host-directory-picker-browse",
+  "description": "In-app browsing backend of the directory-picker seam (listing/creation primitives over the host filesystem)",
+  "version": "0.1.2-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/host/directory-picker-browse"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@prettier-ai/dsh-host-directory-picker": "^0.1.2-alpha.1",
+    "@prettier-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@prettier-ai/cordis": "^4.0.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1"
+  },
+  "devDependencies": {
+    "@prettier-ai/cordis": "^4.0.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1"
+  }
+}