@x1a0f3n9/dsh-host-directory-picker-auto 0.1.5-rc.3

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-auto/README.md
+README.md: a36d7e115f78089b85c79ae8036d7199df74b821
+README.zh.md: 283f8c5bcbfabfa4fdeafc73283ff140ac1697fe

package/README.md

@@ -0,0 +1,122 @@
+---
+description: "Adaptive chooser of the directory-picker seam: resolves the web GUI host's situation once at boot and mounts the matching native or browse backend."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-host-directory-picker-auto
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-host-directory-picker-auto` picks the right directory-picking interaction for every boot: it resolves the host's situation once at boot and mounts the matching backend — [native](../directory-picker-native/README.md) or [browse](../directory-picker-browse/README.md) — together with its browser half, as real Loader entries in the in-memory root tree. The resolution is one pure boot-time sample: `native` requires a loopback-only bind, a non-SSH launch, and a servable display session; anything ambiguous resolves to `browse`, which works everywhere. Pinning an interaction means composing that backend directly. The mounted capability stays stable for the service lifetime, as the seam requires.
+
+## 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 plugin instead of a concrete backend when the same composition must serve hosts that differ: local workstation sessions where a native chooser works, and remote or headless sessions where only the in-app browser works. The chooser inspects the host once at boot and mounts the matching interaction.
+
+### How the choice is made
+
+`native` requires every signal that the operator can see the host display and the native backend can serve it: a loopback-only bind (read from the injected `webServer`; an all-interfaces bind admits remote browsers no OS chooser can reach), no SSH launch (the shared [launch-environment](../../util/launch-environment/README.md) predicate ignores project/user `.env` values and checks only inherited non-empty `SSH_CONNECTION`/`SSH_TTY`), and a servable display session — assumed on darwin and win32; on linux, `DISPLAY`/`WAYLAND_DISPLAY` plus a zenity or kdialog binary on `PATH`; never on any other platform. Anything ambiguous resolves to `browse`, which works everywhere.
+
+### What you get
+
+The resolved interaction arrives as an ordinary Loader entry: the backend registers `ctx.directoryPicker`, and its browser half is discovered by the client module table exactly as a config row's would be, so the seam's one-row-swaps-both-faces invariant holds. Unloading the chooser removes the entry, unloading both faces with it. The sample happens exactly once per boot, so the mounted capability stays stable for the service lifetime.
+
+### Pinning an interaction
+
+Pinning is not a config field here: compose the `-native` or `-browse` row directly instead of this one — that is the seam's documented swap point. Mounting the chooser and a backend row together fails loud (duplicate `directoryPicker` service, duplicate client flow in the `single` holes).
+
+### Observable failures
+
+A wrong `native` choice degrades to the backend's existing retryable failure dialog rather than a broken composition; composing `-browse` directly selects the safe interaction for deployments whose situation the probe cannot prove.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+### Design concept
+
+The chooser is a pure decision plus a mount: `resolveDirectoryPickerBackend` samples host facts once at boot and returns a backend kind, and `apply` mounts the matching backend and surface packages as real Loader entries in the in-memory root tree — never persisted to a config file, because the root tree's `write()` is a no-op. The effect's disposer removes both entries and joins their fibers' teardown, so unloading returns only after both faces of the mounted interaction quiesced.
+
+### The resolution table
+
+| Condition | Backend |
+|---|---|
+| Bind host is not `127.0.0.1` | `browse` |
+| `SSH_CONNECTION` or `SSH_TTY` present | `browse` |
+| darwin or win32 | `native` |
+| linux with a chooser binary and a display | `native` |
+| anything else | `browse` |
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `BACKEND_PACKAGES`/`SURFACE_PACKAGES` maps, `apply` mount and unmount |
+| [`src/resolve.ts`](src/resolve.ts) | `resolveDirectoryPickerBackend` — the pure boot-time decision |
+| [`src/probe.ts`](src/probe.ts) | Host probes: `hasLinuxChooserBinary`, `canExecute` |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these when the chooser's contract is not enough: the seam definition first, then the two backends it mounts.
+
+- [Directory-picker seam](../directory-picker/README.md) — the capability contract the chooser composes.
+- [Directory-picker capability seam decision](../../../.agents/notes/archived/architecture/2026-07-28-directory-picker-capability-seam.md) — why backends differ in interaction shape.
+- [Native backend](../directory-picker-native/README.md) — the interaction mounted for a local operator.
+- [Browse backend](../directory-picker-browse/README.md) — the interaction mounted everywhere else.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the GUI host's directory-selection chooser only mounts a backend row and 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 when the boot-time sample can misjudge the host. They are current package constraints, not a task backlog.
+
+- **Detection infers operator location from launch context, which no launch-side signal can prove** — a tmux session detached from its SSH launch loses the `SSH_*` markers; a Darwin process outside an Aqua session still counts as displayed; and a workstation-local launch later reached through `ssh -L` arrives from `127.0.0.1`, resolves `native`, and opens the chooser on the unattended workstation. A wrong `native` choice degrades to the backend's existing retryable failure dialog, and composing `-browse` directly selects the safe interaction for such deployments.
+- **The Linux chooser probe reads `PATH` only** — a zenity/kdialog reachable some other way (shell alias, non-PATH install) still resolves `browse`; installing either binary on `PATH` restores `native` eligibility at the next boot.
+- **Boot-time only** — one resolution serves every client of the boot; per-connection adaptivity (native for a local browser, browse for a remote one, same server) would need a per-client capability and the wire advertisement the seam does not carry, and waits for a deployment that serves both at once.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. The sole effect is one boot-time Loader-entry mount owned by the plugin fiber; the store is authoritative.

package/README.zh.md

@@ -0,0 +1,122 @@
+---
+description: "目录选择 seam 的自适应选择器：在启动时判定一次 web GUI 宿主的处境，并挂载匹配的原生或浏览后端。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-host-directory-picker-auto
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-host-directory-picker-auto` 为每次启动选出正确的目录选择交互：它在启动时一次性判定宿主处境，并把匹配的后端——[原生](../directory-picker-native/README.zh.md)或[浏览](../directory-picker-browse/README.zh.md)——连同其 browser 半侧一起，作为真实的 Loader 条目挂进内存根树。判定是一次纯函数的启动时采样：`native` 要求仅回环绑定、非 SSH 启动与可服务的显示会话；任何含糊情形都判定为处处可用的 `browse`。固定某种交互就是直接组合那个后端。挂载的能力在服务生命周期内保持稳定，符合 seam 的要求。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当同一份组合必须服务处境不同的宿主时，用本插件代替具体的后端：本地工作站会话里原生选择器可用，远程或无头会话里只有应用内浏览器可用。选择器在启动时检查一次宿主，并挂载匹配的交互。
+
+### 选择是如何作出的
+
+`native` 要求「操作者看得到宿主屏幕、且原生后端能服务它」的全部信号：仅回环的绑定（从注入的 `webServer` 读取；全网卡绑定会接入任何 OS 选择器都触及不到的远程浏览器）；非 SSH 启动（共用的 [launch-environment](../../util/launch-environment/README.zh.md) 判断忽略项目与用户 `.env` 中的值，只检查继承的非空 `SSH_CONNECTION`／`SSH_TTY`）；以及可服务的显示会话——darwin 与 win32 上视为存在；linux 上要求 `DISPLAY`／`WAYLAND_DISPLAY`，外加 `PATH` 上有 zenity 或 kdialog 二进制；其余任何平台上都不成立。任何含糊情形都判定为处处可用的 `browse`。
+
+### 你会得到什么
+
+判定出的交互以普通 Loader 条目的形式到达：后端注册 `ctx.directoryPicker`，其 browser 半侧被 client 模块表发现的方式与配置行完全相同，因此 seam 的「一行同时换两面」不变式依然成立。卸载该选择器会移除该条目，连同两面一起卸载。采样每次启动恰好发生一次，因此挂载的能力在服务生命周期内保持稳定。
+
+### 固定某种交互
+
+固定交互在这里不是配置字段：直接组合 `-native` 或 `-browse` 行来替代本行——那才是 seam 文档化的切换点。同时挂载选择器**和**某个后端行会明确报错（重复的 `directoryPicker` 服务、`single` 类 slot 中的重复 client 流程）。
+
+### 可观察的失败
+
+错误的 `native` 选择会退化为后端既有的可重试失败对话框，而不是坏掉的组合；对探查无法证明其处境的部署，直接组合 `-browse` 即选择安全的交互。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+### 设计理念
+
+选择器是一次纯决策加一次挂载：`resolveDirectoryPickerBackend` 在启动时采样宿主事实并返回一个后端类型，`apply` 把匹配的后端与界面包作为真实 Loader 条目挂进内存根树——绝不持久化到配置文件，因为根树的 `write()` 是 no-op。该 effect 的 disposer 会移除两个条目并汇合其 fiber 的拆除，因此卸载只在所挂载交互的两面完全停稳后返回。
+
+### 判定表
+
+| 条件 | 后端 |
+|---|---|
+| 绑定宿主不是 `127.0.0.1` | `browse` |
+| 存在 `SSH_CONNECTION` 或 `SSH_TTY` | `browse` |
+| darwin 或 win32 | `native` |
+| linux 且带选择器二进制与显示 | `native` |
+| 其他任何情况 | `browse` |
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`BACKEND_PACKAGES`／`SURFACE_PACKAGES` 映射、`apply` 挂载与卸载 |
+| [`src/resolve.ts`](src/resolve.ts) | `resolveDirectoryPickerBackend`——纯函数的启动时决策 |
+| [`src/probe.ts`](src/probe.ts) | 宿主探查：`hasLinuxChooserBinary`、`canExecute` |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当选择器的约定不够用时阅读以下内容：先看 seam 定义，再看它挂载的两个后端。
+
+- [目录选择 seam](../directory-picker/README.zh.md)——选择器所组合的能力约定。
+- [目录选择能力 seam 决策](../../../.agents/notes/archived/architecture/2026-07-28-directory-picker-capability-seam.md)——后端为何在交互形态上彼此不同。
+- [原生后端](../directory-picker-native/README.zh.md)——为本地操作者挂载的交互。
+- [浏览后端](../directory-picker-browse/README.zh.md)——在其他任何地方挂载的交互。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。GUI 宿主的目录选择选择器只挂载一个后端行，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明启动时采样何时会误判宿主。它们是当前包约束，不是任务积压。
+
+- **探测是从启动上下文推断操作者位置，而任何启动侧信号都无法证明这一点**——从 SSH 启动中脱离的 tmux 会话会丢失 `SSH_*` 标记；Aqua 会话之外的 Darwin 进程仍被算作有显示；在工作站本地启动、之后经 `ssh -L` 访问时，请求会从 `127.0.0.1` 到达，系统会判定 `native`，并把选择器弹在无人值守的工作站上。错误的 `native` 选择会退化为后端既有的可重试失败对话框，而对这类部署，直接组合 `-browse` 即选择安全的交互。
+- **Linux 选择器探查只读 `PATH`**——以其他途径可用的 zenity／kdialog（shell 别名、未装在 PATH 上）仍判定为 `browse`；把任一二进制装到 `PATH` 上，下次启动即恢复 `native` 资格。
+- **仅在启动时判定**——一次判定服务本次启动的所有客户端；按连接自适应（同一台服务器，本地浏览器用 native、远程浏览器用 browse）需要按客户端的能力对象以及 seam 未携带的协议通告，等到出现同时服务两种形态的部署再做。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。唯一 effect 是由插件 fiber 持有的 boot-time Loader-entry mount，存储是权威来源。

package/lib/index.js

@@ -0,0 +1,143 @@
+import { launchEnvironmentOf, launchedThroughSsh } from "@x1a0f3n9/dsh-launch-environment";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+//#region lib/types/probe.js
+/**
+* PATH probe for the native backend's Linux chooser binaries: one boot-time
+* sampled fact for the resolver, so an attended Linux host without
+* zenity/kdialog keeps the working `browse` interaction instead of a backend
+* whose every pick fails.
+* @module @x1a0f3n9/dsh-host-directory-picker-auto/probe
+*/
+/** The chooser binaries the native backend can drive on Linux (zenity, KDialog fallback). */
+const LINUX_CHOOSER_BINARIES = ["zenity", "kdialog"];
+/**
+* Whether the current process may execute the candidate path.
+* @param candidate - absolute or PATH-joined file path.
+* @returns true only for an existing executable file.
+*/
+function canExecute(candidate) {
+	try {
+		accessSync(candidate, constants.X_OK);
+	} catch {
+		return false;
+	}
+	return true;
+}
+/**
+* Scan a PATH value for one of the native backend's Linux chooser binaries.
+* @param pathValue - the `PATH` environment value (absent or empty scans nothing).
+* @param isExecutable - executability predicate ({@link canExecute} in production; injected for deterministic tests).
+* @returns whether any PATH directory holds an executable chooser binary.
+*/
+function hasLinuxChooserBinary(pathValue, isExecutable) {
+	for (const dir of (pathValue ?? "").split(delimiter)) {
+		if (dir === "") continue;
+		for (const name of LINUX_CHOOSER_BINARIES) if (isExecutable(join(dir, name))) return true;
+	}
+	return false;
+}
+//#endregion
+//#region lib/types/resolve.js
+/**
+* Boot-time backend resolution for the adaptive directory-picker composition:
+* one pure decision from sampled host facts to a concrete backend kind. The
+* caller samples exactly once per boot, so the mounted capability stays
+* stable for the service lifetime as the seam requires.
+* @module @x1a0f3n9/dsh-host-directory-picker-auto/resolve
+*/
+/** An env value counts only when set and non-blank (an empty export is "unset" by shell convention). */
+const present = (value) => value !== void 0 && value !== "";
+/**
+* Resolve which backend serves this boot. `native` requires every signal that
+* the operator can see the host display and the native backend can serve it:
+* a loopback-only bind (an all-interfaces bind admits remote browsers no OS
+* chooser can reach), no SSH launch (under SSH port-forwarding the chooser
+* would open on the unattended server), and a servable display session —
+* assumed on darwin/win32, requiring `DISPLAY`/`WAYLAND_DISPLAY` plus a
+* chooser binary on linux, and never true elsewhere (the native backend
+* drives exactly darwin/win32/linux). Anything ambiguous resolves to
+* `browse`, which works everywhere.
+* @param facts - the sampled host facts.
+* @returns the backend kind to mount.
+*/
+function resolveDirectoryPickerBackend(facts) {
+	if (facts.bindHost !== "127.0.0.1") return "browse";
+	if (facts.ssh) return "browse";
+	if (facts.platform === "darwin" || facts.platform === "win32") return "native";
+	if (facts.platform !== "linux" || !facts.linuxChooser) return "browse";
+	return present(facts.env.DISPLAY) || present(facts.env.WAYLAND_DISPLAY) ? "native" : "browse";
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Adaptive chooser of the directory-picker seam: resolves the host's
+* situation once at boot (bind host, SSH launch, display session, Linux
+* chooser binary) and mounts the matching interaction — `native` or `browse`
+* — as real Loader entries in the in-memory root tree. Each interaction is a
+* pair: the Host backend serving the seam capability and the client surface
+* occupying ui-workspace's directory-flow holes. Both arrive as ordinary
+* entries, so the surface is discovered exactly as a config-row's would be
+* and one resolved choice still swaps both faces; pinning an interaction
+* remains composing that pair directly instead of this row.
+* @module @x1a0f3n9/dsh-host-directory-picker-auto
+*/
+/** Cordis plugin name. */
+const name = "directory-picker-auto";
+/** Required services: the effective bind host (`webServer`) and the entry tree the backend mounts into (`loader`). */
+const inject = ["webServer", "loader"];
+/**
+* Host backend package per resolved kind — fixed composition vocabulary, not a
+* tunable. Exported because the reference is a runtime string the static
+* config gate cannot see in a yml row: `verify-cordis-config` requires every
+* app composing this chooser to declare both values as dependencies.
+*/
+const BACKEND_PACKAGES = {
+	native: "@x1a0f3n9/dsh-host-directory-picker-native",
+	browse: "@x1a0f3n9/dsh-host-directory-picker-browse"
+};
+/**
+* Client surface package per resolved kind, mounted with its backend so one
+* resolved interaction still composes both faces. Declared as dependencies by
+* every composing app for the same reason as {@link BACKEND_PACKAGES}. Only the
+* specifier is referenced here because the packages belong to the Client
+* program, so no import of them exists on this side.
+*/
+const SURFACE_PACKAGES = {
+	native: "@x1a0f3n9/dsh-client-ui-directory-picker-native",
+	browse: "@x1a0f3n9/dsh-client-ui-directory-picker-browse"
+};
+/**
+* Resolve the interaction from one boot-time sample and mount its backend and
+* surface as Loader entries; the effect's disposer removes both entries and
+* joins their fibers' teardown, so unloading this plugin returns only after
+* both faces of the mounted interaction (and their dependents) quiesced.
+* @param ctx - cordis context carrying the injected `webServer` and `loader`.
+*/
+async function apply(ctx) {
+	const backend = resolveDirectoryPickerBackend({
+		bindHost: ctx.webServer.host,
+		platform: process.platform,
+		ssh: launchedThroughSsh(launchEnvironmentOf(ctx)),
+		env: process.env,
+		linuxChooser: hasLinuxChooserBinary(process.env.PATH, canExecute)
+	});
+	await ctx.effect(async () => {
+		const ids = [];
+		const unmount = async () => {
+			for (const id of [...ids].reverse()) {
+				if (ctx.loader.store[id] === void 0) continue;
+				await ctx.loader.remove(id);
+			}
+		};
+		try {
+			for (const name of [BACKEND_PACKAGES[backend], SURFACE_PACKAGES[backend]]) ids.push(await ctx.loader.create({ name }));
+		} catch (cause) {
+			await unmount();
+			throw cause;
+		}
+		return unmount;
+	}, "directory-picker-auto: interaction entries");
+}
+//#endregion
+export { BACKEND_PACKAGES, SURFACE_PACKAGES, apply, canExecute, hasLinuxChooserBinary, inject, name, resolveDirectoryPickerBackend };

package/lib/types/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Adaptive chooser of the directory-picker seam: resolves the host's
+ * situation once at boot (bind host, SSH launch, display session, Linux
+ * chooser binary) and mounts the matching interaction — `native` or `browse`
+ * — as real Loader entries in the in-memory root tree. Each interaction is a
+ * pair: the Host backend serving the seam capability and the client surface
+ * occupying ui-workspace's directory-flow holes. Both arrive as ordinary
+ * entries, so the surface is discovered exactly as a config-row's would be
+ * and one resolved choice still swaps both faces; pinning an interaction
+ * remains composing that pair directly instead of this row.
+ * @module @x1a0f3n9/dsh-host-directory-picker-auto
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { DirectoryPickerBackendKind } from './resolve.ts';
+export { canExecute, hasLinuxChooserBinary } from './probe.ts';
+export type { DirectoryPickerBackendKind, DirectoryPickerEnv, DirectoryPickerHostFacts } from './resolve.ts';
+export { resolveDirectoryPickerBackend } from './resolve.ts';
+/** Cordis plugin name. */
+export declare const name = "directory-picker-auto";
+/** Required services: the effective bind host (`webServer`) and the entry tree the backend mounts into (`loader`). */
+export declare const inject: string[];
+/**
+ * Host backend package per resolved kind — fixed composition vocabulary, not a
+ * tunable. Exported because the reference is a runtime string the static
+ * config gate cannot see in a yml row: `verify-cordis-config` requires every
+ * app composing this chooser to declare both values as dependencies.
+ */
+export declare const BACKEND_PACKAGES: Record<DirectoryPickerBackendKind, string>;
+/**
+ * Client surface package per resolved kind, mounted with its backend so one
+ * resolved interaction still composes both faces. Declared as dependencies by
+ * every composing app for the same reason as {@link BACKEND_PACKAGES}. Only the
+ * specifier is referenced here because the packages belong to the Client
+ * program, so no import of them exists on this side.
+ */
+export declare const SURFACE_PACKAGES: Record<DirectoryPickerBackendKind, string>;
+/**
+ * Resolve the interaction from one boot-time sample and mount its backend and
+ * surface as Loader entries; the effect's disposer removes both entries and
+ * joins their fibers' teardown, so unloading this plugin returns only after
+ * both faces of the mounted interaction (and their dependents) quiesced.
+ * @param ctx - cordis context carrying the injected `webServer` and `loader`.
+ */
+export declare function apply(ctx: Context): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/probe.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PATH probe for the native backend's Linux chooser binaries: one boot-time
+ * sampled fact for the resolver, so an attended Linux host without
+ * zenity/kdialog keeps the working `browse` interaction instead of a backend
+ * whose every pick fails.
+ * @module @x1a0f3n9/dsh-host-directory-picker-auto/probe
+ */
+/**
+ * Whether the current process may execute the candidate path.
+ * @param candidate - absolute or PATH-joined file path.
+ * @returns true only for an existing executable file.
+ */
+export declare function canExecute(candidate: string): boolean;
+/**
+ * Scan a PATH value for one of the native backend's Linux chooser binaries.
+ * @param pathValue - the `PATH` environment value (absent or empty scans nothing).
+ * @param isExecutable - executability predicate ({@link canExecute} in production; injected for deterministic tests).
+ * @returns whether any PATH directory holds an executable chooser binary.
+ */
+export declare function hasLinuxChooserBinary(pathValue: string | undefined, isExecutable: (candidate: string) => boolean): boolean;
+//# sourceMappingURL=probe.d.ts.map

package/lib/types/resolve.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Boot-time backend resolution for the adaptive directory-picker composition:
+ * one pure decision from sampled host facts to a concrete backend kind. The
+ * caller samples exactly once per boot, so the mounted capability stays
+ * stable for the service lifetime as the seam requires.
+ * @module @x1a0f3n9/dsh-host-directory-picker-auto/resolve
+ */
+import type { Config as HttpServerConfig } from '@x1a0f3n9/dsh-host-webserver';
+/** Concrete interaction backend the resolver chooses between. */
+export type DirectoryPickerBackendKind = 'native' | 'browse';
+/** Environment keys the resolution reads (a `process.env` subset). */
+export type DirectoryPickerEnv = Readonly<Partial<Record<'DISPLAY' | 'WAYLAND_DISPLAY', string>>>;
+/** Host facts the backend choice is a pure function of, sampled once at boot. */
+export interface DirectoryPickerHostFacts {
+    /** Effective webserver bind host (the schema's closed loopback/all-interfaces union). */
+    bindHost: HttpServerConfig['host'];
+    /** Host process platform. */
+    platform: NodeJS.Platform;
+    /** SSH launch fact from the inherited process layer, independent of `.env` values. */
+    ssh: boolean;
+    /** Environment sample; DISPLAY/WAYLAND_DISPLAY marks a Linux display. */
+    env: DirectoryPickerEnv;
+    /** Whether a Linux chooser binary the native backend can drive (zenity/kdialog) is on PATH; consulted only when `platform` is linux. */
+    linuxChooser: boolean;
+}
+/**
+ * Resolve which backend serves this boot. `native` requires every signal that
+ * the operator can see the host display and the native backend can serve it:
+ * a loopback-only bind (an all-interfaces bind admits remote browsers no OS
+ * chooser can reach), no SSH launch (under SSH port-forwarding the chooser
+ * would open on the unattended server), and a servable display session —
+ * assumed on darwin/win32, requiring `DISPLAY`/`WAYLAND_DISPLAY` plus a
+ * chooser binary on linux, and never true elsewhere (the native backend
+ * drives exactly darwin/win32/linux). Anything ambiguous resolves to
+ * `browse`, which works everywhere.
+ * @param facts - the sampled host facts.
+ * @returns the backend kind to mount.
+ */
+export declare function resolveDirectoryPickerBackend(facts: DirectoryPickerHostFacts): DirectoryPickerBackendKind;
+//# sourceMappingURL=resolve.d.ts.map

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@x1a0f3n9/dsh-host-directory-picker-auto",
+  "description": "Adaptive chooser of the directory-picker seam: resolves the host situation at boot and mounts the native or browse backend for the DeepSeek Harness web GUI host",
+  "version": "0.1.5-rc.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/host/directory-picker-auto"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@x1a0f3n9/dsh-client-ui-directory-picker-browse": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-client-ui-directory-picker-native": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-host-directory-picker-browse": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-host-directory-picker-native": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-host-webserver": "^0.1.5-rc.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@x1a0f3n9/dsh-client-ui-directory-picker-browse": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-client-ui-directory-picker-native": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-host-directory-picker": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-host-directory-picker-browse": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-host-directory-picker-native": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-host-webserver": "^0.1.5-rc.3"
+  },
+  "dependencies": {
+    "@x1a0f3n9/dsh-launch-environment": "^0.1.5-rc.3"
+  }
+}