feat(host): directory-picker capability seam with dialog and browse backends

The web GUI's folder picking was hardwired to one interaction: a native
OS chooser compiled into the gateway, unusable for remote deployments
and swappable only by editing apiproxy source.

Directory picking becomes a three-package capability seam in
packages/host: ctx.directoryPicker returns a discriminated capability —
dialog (the extracted native chooser; host-display only) or browse
(new: one-level listing + child creation over Node stdlib, hidden flags
host-stamped, symlinks followed, ancestry crumbs; remote-capable). The
gateway injects the seam, advertises the kind via
host.describe.directoryPicker, serves host.listDirectory /
host.createDirectory under browse, and answers
directory-picker-unavailable across kinds. cordis.yml is the swap
point; apps/cli keeps dialog mounted, so behavior is unchanged until
the in-app browser PR flips the default. The connection fixture serves
a deterministic browse tree; WorkspacesService gains the browse calls
the browser UI will drive. Decision record:
.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md

packages/host/directory-picker-browse/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: f86f74acf4922d490b23c033a281436f1a428f13
+README.zh.md: 0d240630a8b21003c5285bc75e93aac9adf36d92

packages/host/directory-picker-browse/README.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-host-directory-picker-browse
+
+English | [中文](README.zh.md)
+
+The **in-app browsing backend** of the [directory-picker seam](../directory-picker/README.md): `BrowseDirectoryPicker` registers `ctx.directoryPicker` with the `browse` capability — one-level directory listing and child-directory creation over 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.
+
+Behavior facts: listings return **directories only**, name-sorted, with symlinks-to-directories followed (broken/cyclic links skipped — the probe `stat` failing means "not enterable") and a host-owned `hidden` flag (POSIX dot convention) left for the client to act on; `crumbs` is the root-to-target ancestor chain, the root crumb labeled by its full path (`/`, `C:\`); an absent `list` path means the host account's home directory. `createDirectory` is non-recursive (a missing parent is a real failure, not a level to invent) and validates the name as a single non-blank segment even when called directly, mirroring the wire schema's fence. Failures throw the seam's typed `DirectoryPickerError`. Policy rationale: [the directory-picker capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md).
+
+## Model Experience
+
+None, as the backend serves the GUI host's directory selection; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **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** — no per-deployment browse-root restriction; `workspace.create` accepts arbitrary paths today, so a root here would be UX scoping, not a boundary — deferred until a deployment needs it.

packages/host/directory-picker-browse/README.zh.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-host-directory-picker-browse
+
+[English](README.md) | 中文
+
+[目录选择 seam](../directory-picker/README.md) 的**应用内浏览后端**：`BrowseDirectoryPicker` 以 `browse` 能力注册 `ctx.directoryPicker`——基于 Node 标准库（跨 OS 适配本就由它承担）提供单层目录列举与子目录创建。宿主屏幕上不渲染任何东西，因此该后端能服务 dialog 后端无法触及的远程客户端。
+
+行为事实：列举**只返回目录**、按名称排序，指向目录的符号链接会被跟随（断链／循环链接被跳过——探测 `stat` 失败即"不可进入"），并携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示决策留给客户端；`crumbs` 是从根到目标的祖先链，根 crumb 以完整路径标注（`/`、`C:\`）；`list` 不带路径即列举宿主账户的家目录。`createDirectory` 不递归（父目录缺失是真实失败，不是要补造的层级），且即便被直接调用也把名称校验为单个非空段，与协议 schema 的栅栏一致。失败抛出 seam 的类型化 `DirectoryPickerError`。策略依据：[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。
+
+## 模型体验
+
+无。该后端服务于 GUI 宿主的目录选择；这里没有任何内容进入模型请求。
+
+#### KV 缓存影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **不读取 Windows 隐藏属性**——Node 的 dirent 不暴露 `FILE_ATTRIBUTE_HIDDEN`，因此在所有平台上 `hidden` 都意味着点前缀，直到原生探测值回其成本为止。
+- **不枚举盘符根**——Windows 上祖先链止于盘符根；跨盘依赖浏览器 UI 的路径输入入口，而不是这里的枚举原语。
+- **全盘可浏览**——没有按部署限定的浏览根；`workspace.create` 今天就接受任意路径，这里的根只会是 UX 范围而非边界——等到有部署需要时再做。

packages/host/directory-picker-browse/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@deepseek-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.0.1",
+  "private": true,
+  "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",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-host-directory-picker": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/host/directory-picker-browse/src/index.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 @deepseek-ai/dsh-host-directory-picker-browse
+ */
+
+import { mkdir, readdir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+import {
+  DirectoryPicker, DirectoryPickerError,
+} from '@deepseek-ai/dsh-host-directory-picker'
+import type {
+  DirectoryEntry, DirectoryListing, DirectoryPickerCapability,
+} from '@deepseek-ai/dsh-host-directory-picker'
+
+/**
+ * Ancestor chain from the filesystem root to `target` inclusive — the
+ * breadcrumb rows of a listing, every one a jump target.
+ */
+function ancestryCrumbs(target: string): DirectoryEntry[] {
+  const crumbs: DirectoryEntry[] = []
+  let current = target
+  for (;;) {
+    const parent = dirname(current)
+    // basename of a root is '' — label the root crumb by its full path ('/', 'C:\').
+    crumbs.unshift({ name: parent === current ? current : basename(current), path: current, hidden: false })
+    if (parent === current) return crumbs
+    current = parent
+  }
+}
+
+/** Message text of an unknown thrown value. */
+function messageOf(error: unknown): string {
+  /* 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: string, name: string, isDirectory: boolean, isSymbolicLink: boolean): Promise<DirectoryEntry | null> {
+  const path = join(parent, name)
+  let enterable = isDirectory
+  if (!enterable && isSymbolicLink) {
+    try {
+      enterable = (await stat(path)).isDirectory()
+    } catch {
+      // Broken or cyclic symlink: stat is the probe, failure means "not enterable".
+      return null
+    }
+  }
+  if (!enterable) return null
+  // POSIX hidden convention; Windows' hidden attribute is not exposed by
+  // dirents (Known Limitations). The client owns whether hidden rows show.
+  return { name, path, hidden: name.startsWith('.') }
+}
+
+/** The `ctx.directoryPicker` browse implementation (stable capability object per service life). */
+export default class BrowseDirectoryPicker extends DirectoryPicker {
+  private readonly browseCapability: DirectoryPickerCapability = {
+    kind: 'browse',
+    list: path => this.list(path),
+    createDirectory: (path, name) => this.createDirectory(path, name),
+  }
+
+  /**
+   * The browse interaction capability.
+   * @returns the stable `browse` capability object.
+   */
+  capability(): DirectoryPickerCapability {
+    return this.browseCapability
+  }
+
+  private async list(path?: string): Promise<DirectoryListing> {
+    const home = homedir()
+    const target = resolve(path ?? home)
+    let names: { name: string; isDirectory: boolean; isSymbolicLink: boolean }[]
+    try {
+      const dirents = await readdir(target, { withFileTypes: true })
+      names = dirents.map(dirent => ({
+        name: dirent.name,
+        isDirectory: dirent.isDirectory(),
+        isSymbolicLink: dirent.isSymbolicLink(),
+      }))
+    } catch (error: unknown) {
+      throw new DirectoryPickerError('directory-unreadable', target, `cannot list ${target}: ${messageOf(error)}`)
+    }
+    const rows = await Promise.all(names.map(entry => directoryRow(target, entry.name, entry.isDirectory, entry.isSymbolicLink)))
+    const entries = rows.filter((row): row is DirectoryEntry => row !== null)
+      .sort((a, b) => a.name.localeCompare(b.name))
+    return { path: target, home, crumbs: ancestryCrumbs(target), entries }
+  }
+
+  private async createDirectory(path: string, name: string): Promise<string> {
+    const parent = resolve(path)
+    // The backend owns segment validation (the wire schema also refuses these,
+    // but direct service consumers must hit the same fence).
+    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 {
+      // Non-recursive: the parent is the directory the browser is showing, so
+      // a missing parent is a real failure, not a level to invent.
+      await mkdir(target)
+      return target
+    } catch (error: unknown) {
+      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)}`)
+    }
+  }
+}

packages/host/directory-picker-browse/src/invariant.ts

@@ -0,0 +1,25 @@
+/**
+ * Package-owned invariant companion for the browse directory-picker backend.
+ * @module @deepseek-ai/dsh-host-directory-picker-browse/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-directory-picker-browse'
+
+/** Cordis companion plugin name. */
+export const name = 'host-directory-picker-browse-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: each list/create is one stateless filesystem round trip; the filesystem itself is the authoritative state. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * 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 const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/host/directory-picker-browse/tests/service.spec.ts

@@ -0,0 +1,96 @@
+/** Behavior of the browse backend over a real temporary directory tree. */
+
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { DirectoryPickerError } from '@deepseek-ai/dsh-host-directory-picker'
+import type { DirectoryPickerBrowseCapability } from '@deepseek-ai/dsh-host-directory-picker'
+import BrowseDirectoryPicker from '../src/index.ts'
+
+let root: string
+let capability: DirectoryPickerBrowseCapability
+let dispose: () => Promise<void>
+
+beforeAll(async () => {
+  root = await mkdtemp(join(tmpdir(), 'dsh-browse-'))
+  await mkdir(join(root, 'projects'))
+  await mkdir(join(root, 'projects', 'harness'))
+  await mkdir(join(root, '.hidden-dir'))
+  await writeFile(join(root, 'notes.txt'), 'not a directory')
+  await symlink(join(root, 'projects'), join(root, 'linked'), 'junction')
+  await symlink(join(root, 'gone'), join(root, 'broken'), 'junction')
+
+  const ctx = new Context()
+  const fiber = ctx.plugin(BrowseDirectoryPicker)
+  await fiber.await()
+  const picked = ctx.get('directoryPicker')!.capability()
+  if (picked.kind !== 'browse') throw new Error('browse backend must advertise the browse capability')
+  capability = picked
+  dispose = () => fiber.dispose()
+})
+
+afterAll(async () => {
+  await dispose()
+  await rm(root, { recursive: true, force: true })
+})
+
+describe('BrowseDirectoryPicker', () => {
+  it('lists directories only, flags hidden rows, follows symlinks, skips broken links, sorts by name', async () => {
+    const listing = await capability.list(root)
+    expect(listing.path).toBe(root)
+    expect(listing.home).toBe(homedir())
+    expect(listing.entries.map(entry => entry.name)).toEqual(['.hidden-dir', 'linked', 'projects'])
+    expect(listing.entries.map(entry => entry.hidden)).toEqual([true, false, false])
+    // Every entry path is absolute and host-joined — clients never join segments.
+    expect(listing.entries.every(entry => entry.path === join(root, entry.name))).toBe(true)
+  })
+
+  it('reports the ancestry as jump-target crumbs ending at the listed directory', async () => {
+    const listing = await capability.list(join(root, 'projects'))
+    const tail = listing.crumbs.at(-1)!
+    expect(tail).toMatchObject({ name: 'projects', path: join(root, 'projects'), hidden: false })
+    expect(listing.crumbs.at(-2)!.path).toBe(root)
+    expect(listing.crumbs.at(-2)!.name).toBe(basename(root))
+    // The chain starts at the filesystem root, whose crumb is labeled by its full path.
+    expect(listing.crumbs[0]!.name).toBe(listing.crumbs[0]!.path)
+  })
+
+  it('lists the home directory when no path is given', async () => {
+    const listing = await capability.list()
+    expect(listing.path).toBe(homedir())
+  })
+
+  it('throws directory-unreadable for a missing target', async () => {
+    const missing = join(root, 'no-such-dir')
+    const failure = await capability.list(missing).catch((error: unknown) => error)
+    expect(failure).toBeInstanceOf(DirectoryPickerError)
+    expect((failure as DirectoryPickerError).code).toBe('directory-unreadable')
+    expect((failure as DirectoryPickerError).path).toBe(missing)
+  })
+
+  it('creates one child directory and surfaces it in the next listing', async () => {
+    const created = await capability.createDirectory(root, 'fresh')
+    expect(created).toBe(join(root, 'fresh'))
+    const listing = await capability.list(root)
+    expect(listing.entries.map(entry => entry.name)).toContain('fresh')
+  })
+
+  it('refuses an existing child with directory-exists', async () => {
+    const failure = await capability.createDirectory(root, 'projects').catch((error: unknown) => error)
+    expect(failure).toBeInstanceOf(DirectoryPickerError)
+    expect((failure as DirectoryPickerError).code).toBe('directory-exists')
+  })
+
+  it('refuses non-segment names and other filesystem failures with directory-create-failed', async () => {
+    for (const name of ['', '  ', '.', '..', 'a/b', 'a\\b']) {
+      const failure = await capability.createDirectory(root, name).catch((error: unknown) => error)
+      expect(failure).toBeInstanceOf(DirectoryPickerError)
+      expect((failure as DirectoryPickerError).code).toBe('directory-create-failed')
+    }
+    // Missing parent is a real failure, not a level to invent.
+    const missingParent = await capability.createDirectory(join(root, 'no-such-dir'), 'child').catch((error: unknown) => error)
+    expect((missingParent as DirectoryPickerError).code).toBe('directory-create-failed')
+  })
+})

packages/host/directory-picker-browse/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../directory-picker"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}