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/apiproxy/src/api-proxy.ts

@@ -39,7 +39,7 @@ import type {
   AskUserQuestionAnswer, AskUserQuestionItem, AskUserQuestionRequest,
 } from '@deepseek-ai/dsh-user-interaction'
 import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
-import { pickNativeDirectory } from './native-directory-picker.ts'
+import { DirectoryPickerError } from '@deepseek-ai/dsh-host-directory-picker'
 
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
@@ -193,6 +193,14 @@ async function summarizeCold(persistence: SessionPersistence, meta: SessionHeade
   }
 }
 
+/** Map a browse-primitive failure onto the wire error vocabulary (unknown throws stay internal). */
+function directoryError(error: unknown): RpcError {
+  if (error instanceof DirectoryPickerError) {
+    return { code: error.code, message: error.message, details: { path: error.path } }
+  }
+  return { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} }
+}
+
 /** Resolved Host routing and project-directory defaults consumed by the API implementation. */
 export interface ApiProxyDefaults {
   provider: string
@@ -201,8 +209,6 @@ export interface ApiProxyDefaults {
   cwd: string
   /** Parent directory for name-created workspaces. */
   workspaceRoot: string
-  /** Native single-directory picker; injectable for carrier tests. */
-  pickDirectory?: (signal: AbortSignal) => Promise<string | null>
 }
 
 /** The tool/call payload fields the presenter path reads. */
@@ -990,12 +996,21 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           provider: defaults.provider,
           model: defaults.model,
           attachedSessions: ctx.agents.list().length,
+          directoryPicker: ctx.directoryPicker.capability().kind,
         }))
       },
 
       async pickDirectory(request, signal) {
+        const capability = ctx.directoryPicker.capability()
+        if (capability.kind !== 'dialog') {
+          return err(request, {
+            code: 'directory-picker-unavailable',
+            message: `host.pickDirectory needs the dialog capability; the composed picker serves "${capability.kind}"`,
+            details: { capability: capability.kind },
+          })
+        }
         try {
-          const path = await (defaults.pickDirectory ?? pickNativeDirectory)(signal)
+          const path = await capability.pick(signal)
           return ok(request, { path })
         } catch (error: unknown) {
           if (signal.aborted) {
@@ -1012,6 +1027,38 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           })
         }
       },
+
+      async listDirectory(request) {
+        const capability = ctx.directoryPicker.capability()
+        if (capability.kind !== 'browse') {
+          return err(request, {
+            code: 'directory-picker-unavailable',
+            message: `host.listDirectory needs the browse capability; the composed picker serves "${capability.kind}"`,
+            details: { capability: capability.kind },
+          })
+        }
+        try {
+          return ok(request, await capability.list(request.payload.path))
+        } catch (error: unknown) {
+          return err(request, directoryError(error))
+        }
+      },
+
+      async createDirectory(request) {
+        const capability = ctx.directoryPicker.capability()
+        if (capability.kind !== 'browse') {
+          return err(request, {
+            code: 'directory-picker-unavailable',
+            message: `host.createDirectory needs the browse capability; the composed picker serves "${capability.kind}"`,
+            details: { capability: capability.kind },
+          })
+        }
+        try {
+          return ok(request, { path: await capability.createDirectory(request.payload.path, request.payload.name) })
+        } catch (error: unknown) {
+          return err(request, directoryError(error))
+        }
+      },
     },
 
     commands: {

packages/host/apiproxy/src/api/host.schema.ts

@@ -3,6 +3,7 @@
  */
 
 import { z } from 'zod'
+import type { DirectoryEntry } from './host.ts'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 
@@ -16,6 +17,7 @@ export const hostDescribeValueSchema = z.object({
   provider: z.string().optional(),
   model: z.string().optional(),
   attachedSessions: z.number().int().nonnegative(),
+  directoryPicker: z.union([z.literal('dialog'), z.literal('browse')]),
 }) satisfies z.ZodType<Wire<ResponseValue<'host.describe'>>>
 
 /** host.pickDirectory request payload (empty object literal). */
@@ -25,3 +27,38 @@ export const hostPickDirectoryRequestSchema = z.object({}) satisfies z.ZodType<W
 export const hostPickDirectoryValueSchema = z.object({
   path: z.string().nullable(),
 }) satisfies z.ZodType<Wire<ResponseValue<'host.pickDirectory'>>>
+
+/** Directory row shared by listing entries and breadcrumb crumbs. */
+export const directoryEntrySchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  hidden: z.boolean(),
+}) satisfies z.ZodType<Wire<DirectoryEntry>>
+
+/** host.listDirectory request payload; an absent path lists the home directory. */
+export const hostListDirectoryRequestSchema = z.object({
+  path: z.string().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'host.listDirectory'>>>
+
+/** host.listDirectory response value. */
+export const hostListDirectoryValueSchema = z.object({
+  path: z.string(),
+  home: z.string(),
+  crumbs: z.array(directoryEntrySchema),
+  entries: z.array(directoryEntrySchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.listDirectory'>>>
+
+/** host.createDirectory request payload: name must be one plain path segment. */
+export const hostCreateDirectoryRequestSchema = z.object({
+  path: z.string(),
+  name: z.string(),
+}).refine(
+  payload => payload.name.trim() !== '' && payload.name !== '.' && payload.name !== '..'
+    && !/[/\\]/.test(payload.name),
+  { message: 'host.createDirectory requires a single non-blank path segment name' },
+) satisfies z.ZodType<Wire<RequestPayload<'host.createDirectory'>>>
+
+/** host.createDirectory response value: the created directory's absolute path. */
+export const hostCreateDirectoryValueSchema = z.object({
+  path: z.string(),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.createDirectory'>>>

packages/host/apiproxy/src/api/host.ts

@@ -5,6 +5,40 @@
 
 import type { RpcRequest, RpcResponse } from './rpc.ts'
 
+/**
+ * The composed directory-picker interaction the host serves (mirror of the
+ * `ctx.directoryPicker` capability kind): `dialog` = one native OS chooser on
+ * the host display (`host.pickDirectory`); `browse` = in-app listing/creation
+ * primitives (`host.listDirectory`/`host.createDirectory`). Calling a method
+ * outside the advertised kind fails with `directory-picker-unavailable`.
+ */
+export type DirectoryPickerKind = 'dialog' | 'browse'
+
+/** One directory row of a listing: a child entry or a breadcrumb ancestor. */
+export interface DirectoryEntry {
+  /** Base name shown in a browser row (a root crumb carries its full path). */
+  name: string
+  /** Absolute host path — the client never joins path segments itself. */
+  path: string
+  /** Hidden by the host platform's convention (dot-prefixed on POSIX); the client owns whether to show it. */
+  hidden: boolean
+}
+
+/** host.listDirectory response value: one directory level plus its ancestry. */
+export interface DirectoryListing {
+  /** Absolute path of the listed directory. */
+  path: string
+  /** The host account's home directory (breadcrumb "Home" rooting). */
+  home: string
+  /**
+   * Ancestor chain from the filesystem root to the listed directory
+   * inclusive; every crumb is a jump target (crumb `hidden` is always false).
+   */
+  crumbs: DirectoryEntry[]
+  /** Direct child directories, name-sorted; symlinks to directories included. */
+  entries: DirectoryEntry[]
+}
+
 /** Host-level unary methods. */
 export interface HostApi {
   /**
@@ -13,7 +47,8 @@ export interface HostApi {
    * directory (root for session persistence and tool execution); provider/model = the defaults
    * applied when a new agent doesn't specify them explicitly, absent when the host configures
    * no explicit default (the adapter falls back internally);
-   * attachedSessions = count of currently attached sessions (those with a live agent).
+   * attachedSessions = count of currently attached sessions (those with a live agent);
+   * directoryPicker = the composed picker interaction the client renders for.
    */
   describe(request: RpcRequest<{}>): Promise<RpcResponse<{
     version: string
@@ -21,11 +56,34 @@ export interface HostApi {
     provider?: string
     model?: string
     attachedSessions: number
+    directoryPicker: DirectoryPickerKind
   }>>
 
-  /** Open the operating system's single-directory picker; cancellation returns null. */
+  /**
+   * Open the operating system's single-directory picker; cancellation returns
+   * null. Only served under the `dialog` capability.
+   */
   pickDirectory(
     request: RpcRequest<{}>,
     signal: AbortSignal,
   ): Promise<RpcResponse<{ path: string | null }>>
+
+  /**
+   * List one directory level for the in-app browser; an absent path lists the
+   * host account's home directory. Only served under the `browse` capability;
+   * unreadable or missing targets fail with `directory-unreadable`.
+   */
+  listDirectory(
+    request: RpcRequest<{ path?: string }>,
+  ): Promise<RpcResponse<DirectoryListing>>
+
+  /**
+   * Create one child directory under an existing parent (the browser's
+   * "New folder"). Only served under the `browse` capability; an existing
+   * child fails with `directory-exists`, every other filesystem failure with
+   * `directory-create-failed`.
+   */
+  createDirectory(
+    request: RpcRequest<{ path: string; name: string }>,
+  ): Promise<RpcResponse<{ path: string }>>
 }

packages/host/apiproxy/src/api/index.ts

@@ -29,7 +29,7 @@ export type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
   ModelReasoningEffort, ModelTarget, SessionModels, SessionsApi, SessionSummary,
 } from './sessions.ts'
-export type { HostApi } from './host.ts'
+export type { DirectoryEntry, DirectoryListing, DirectoryPickerKind, HostApi } from './host.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor, CommandExecuteResult } from './commands.ts'
 export type { SkillsApi, SkillEntry } from './skills.ts'

packages/host/apiproxy/src/api/rpc-map.ts

@@ -26,6 +26,8 @@ export interface RpcMethodMap {
   'session.cancel': SessionsApi['cancel']
   'host.describe': HostApi['describe']
   'host.pickDirectory': HostApi['pickDirectory']
+  'host.listDirectory': HostApi['listDirectory']
+  'host.createDirectory': HostApi['createDirectory']
   'workspace.list': WorkspaceApi['list']
   'workspace.create': WorkspaceApi['create']
   'workspace.rename': WorkspaceApi['rename']

packages/host/apiproxy/src/api/rpc.schema.ts

@@ -42,6 +42,10 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('workspace-invalid-path'), message: z.string(), details: z.object({ path: z.string() }) }),
   z.object({ code: z.literal('workspace-name-conflict'), message: z.string(), details: z.object({ name: z.string() }) }),
   z.object({ code: z.literal('workspace-move-invalid'), message: z.string(), details: z.object({ workspaceId: z.string(), sessionId: z.string(), beforeSessionId: z.string().optional() }) }),
+  z.object({ code: z.literal('directory-unreadable'), message: z.string(), details: z.object({ path: z.string() }) }),
+  z.object({ code: z.literal('directory-exists'), message: z.string(), details: z.object({ path: z.string() }) }),
+  z.object({ code: z.literal('directory-create-failed'), message: z.string(), details: z.object({ path: z.string() }) }),
+  z.object({ code: z.literal('directory-picker-unavailable'), message: z.string(), details: z.object({ capability: z.string() }) }),
   z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
   z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),
 ]) as unknown as z.ZodType<RpcError>

packages/host/apiproxy/src/api/rpc.ts

@@ -39,6 +39,10 @@ export interface RpcErrorDetailsMap {
   'workspace-invalid-path': { path: string }
   'workspace-name-conflict': { name: string }
   'workspace-move-invalid': { workspaceId: string; sessionId: SessionId; beforeSessionId?: SessionId }
+  'directory-unreadable': { path: string }
+  'directory-exists': { path: string }
+  'directory-create-failed': { path: string }
+  'directory-picker-unavailable': { capability: string }
   'agent-busy': { reason: string }
   'internal': {}
 }

packages/host/apiproxy/src/fetch/client.ts

@@ -13,7 +13,10 @@ import { RpcId } from '../api/rpc.ts'
 import type { Wire } from '../api/rpc.schema.ts'
 import { rpcReceiptSchema, serverRequestSchema, serverResponseSchema } from '../api/rpc.schema.ts'
 import { hostFrameSchema, muxFrameSchema } from '../api/events.schema.ts'
-import { hostDescribeValueSchema, hostPickDirectoryValueSchema } from '../api/host.schema.ts'
+import {
+  hostCreateDirectoryValueSchema, hostDescribeValueSchema,
+  hostListDirectoryValueSchema, hostPickDirectoryValueSchema,
+} from '../api/host.schema.ts'
 import {
   sessionCancelValueSchema,
   sessionCreateValueSchema,
@@ -61,6 +64,8 @@ export interface IApiClient {
   host: {
     describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
     pickDirectory(payload: RequestPayload<'host.pickDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.pickDirectory'>>>
+    listDirectory(payload: RequestPayload<'host.listDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.listDirectory'>>>
+    createDirectory(payload: RequestPayload<'host.createDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.createDirectory'>>>
   }
   workspace: {
     list(payload: RequestPayload<'workspace.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.list'>>>
@@ -98,6 +103,8 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'session.cancel': sessionCancelValueSchema,
   'host.describe': hostDescribeValueSchema,
   'host.pickDirectory': hostPickDirectoryValueSchema,
+  'host.listDirectory': hostListDirectoryValueSchema,
+  'host.createDirectory': hostCreateDirectoryValueSchema,
   'workspace.list': workspaceListValueSchema,
   'workspace.create': workspaceCreateValueSchema,
   'workspace.rename': workspaceRenameValueSchema,
@@ -305,6 +312,8 @@ export abstract class AbstractApiClient implements IApiClient {
     // A native system dialog is user-paced and may legitimately stay open
     // longer than the normal unary deadline. Caller/connection aborts remain.
     pickDirectory: (payload, signal) => this.callUnary('host.pickDirectory', payload, signal, false),
+    listDirectory: (payload, signal) => this.callUnary('host.listDirectory', payload, signal),
+    createDirectory: (payload, signal) => this.callUnary('host.createDirectory', payload, signal),
   }
 
   readonly workspace: IApiClient['workspace'] = {

packages/host/apiproxy/src/fetch/handler.ts

@@ -23,7 +23,10 @@ import {
   sessionPromptRequestSchema,
   sessionSelectModelRequestSchema,
 } from '../api/sessions.schema.ts'
-import { hostDescribeRequestSchema, hostPickDirectoryRequestSchema } from '../api/host.schema.ts'
+import {
+  hostCreateDirectoryRequestSchema, hostDescribeRequestSchema,
+  hostListDirectoryRequestSchema, hostPickDirectoryRequestSchema,
+} from '../api/host.schema.ts'
 import {
   workspaceCreateRequestSchema,
   workspaceDeleteRequestSchema,
@@ -60,6 +63,8 @@ const UNARY_ROUTES: UnaryRoutes = {
   'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
   'host.pickDirectory': { schema: hostPickDirectoryRequestSchema, invoke: (api, r, signal) => api.host.pickDirectory(r, signal) },
+  'host.listDirectory': { schema: hostListDirectoryRequestSchema, invoke: (api, r) => api.host.listDirectory(r) },
+  'host.createDirectory': { schema: hostCreateDirectoryRequestSchema, invoke: (api, r) => api.host.createDirectory(r) },
   'workspace.list': { schema: workspaceListRequestSchema, invoke: (api, r) => api.workspace.list(r) },
   'workspace.create': { schema: workspaceCreateRequestSchema, invoke: (api, r) => api.workspace.create(r) },
   'workspace.rename': { schema: workspaceRenameRequestSchema, invoke: (api, r) => api.workspace.rename(r) },

packages/host/apiproxy/src/index.ts

@@ -45,7 +45,7 @@ export interface Config {
  * project directory and the fallback parent for name-created Workspaces.
  */
 export class ApiProxyService extends Service implements ApiProxy {
-  static inject = ['agents', 'llm', 'sessions', 'tools', 'userInteraction', 'workspace']
+  static inject = ['agents', 'directoryPicker', 'llm', 'sessions', 'tools', 'userInteraction', 'workspace']
 
   static Config: z<Config> = z.object({
     provider: z.string().required(),

packages/host/apiproxy/src/native-directory-picker.ts

@@ -1,136 +0,0 @@
-/** Cross-platform native single-directory picker used by the local GUI carrier. */
-
-import { execFile } from 'node:child_process'
-
-/** Testable command boundary; native implementations never invoke a shell. */
-export type DirectoryPickerRunner = (
-  command: string,
-  args: readonly string[],
-  signal: AbortSignal,
-) => Promise<{ stdout: string; stderr: string }>
-
-/** Injectable platform facts for deterministic adapter tests. */
-export interface DirectoryPickerInternals {
-  platform?: NodeJS.Platform
-  run?: DirectoryPickerRunner
-}
-
-const runCommand: DirectoryPickerRunner = (command, args, signal) =>
-  new Promise((resolve, reject) => {
-    execFile(
-      command,
-      [...args],
-      { encoding: 'utf8', signal, windowsHide: true },
-      (error, stdout, stderr) => {
-        if (error !== null) {
-          const failure = Object.assign(new Error(error.message, { cause: error }), {
-            code: error.code,
-            stdout,
-            stderr,
-          })
-          reject(failure)
-          return
-        }
-        resolve({ stdout, stderr })
-      },
-    )
-  })
-
-function outputPath(stdout: string): string | null {
-  const path = stdout.replace(/[\r\n]+$/, '')
-  return path === '' ? null : path
-}
-
-function errorCode(error: unknown): string | number | undefined {
-  if (typeof error !== 'object' || error === null || !('code' in error)) return undefined
-  const code = (error as { code?: unknown }).code
-  return typeof code === 'string' || typeof code === 'number' ? code : undefined
-}
-
-function errorStderr(error: unknown): string {
-  if (typeof error !== 'object' || error === null || !('stderr' in error)) return ''
-  const stderr = (error as { stderr?: unknown }).stderr
-  return typeof stderr === 'string' ? stderr : ''
-}
-
-function isMissingCommand(error: unknown): boolean {
-  return errorCode(error) === 'ENOENT'
-}
-
-function rethrowIfAborted(signal: AbortSignal, error: unknown): void {
-  if (signal.aborted) throw error
-}
-
-/**
- * Open the platform directory picker.
- * @param signal - caller/connection lifetime; abort terminates the native command.
- * @param internals - platform and runner seam for deterministic tests.
- * @returns the selected path, or null when the user cancels.
- */
-export async function pickNativeDirectory(
-  signal: AbortSignal,
-  internals: DirectoryPickerInternals = {},
-): Promise<string | null> {
-  const platform = internals.platform ?? process.platform
-  const run = internals.run ?? runCommand
-
-  if (platform === 'darwin') {
-    try {
-      const result = await run('osascript', [
-        '-e', 'set selectedFolder to choose folder with prompt "Select Workspace Directory"',
-        '-e', 'POSIX path of selectedFolder',
-      ], signal)
-      return outputPath(result.stdout)
-    } catch (error: unknown) {
-      if (!signal.aborted && errorCode(error) === 1
-        && /(?:User canceled|-128)/i.test(errorStderr(error))) return null
-      throw error
-    }
-  }
-
-  if (platform === 'win32') {
-    const script = [
-      "$ErrorActionPreference = 'Stop'",
-      'Add-Type -AssemblyName System.Windows.Forms',
-      '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
-      "$dialog.Description = 'Select Workspace Directory'",
-      '$dialog.ShowNewFolderButton = $true',
-      '$result = $dialog.ShowDialog()',
-      'if ($result -eq [System.Windows.Forms.DialogResult]::OK) {',
-      '  [Console]::OutputEncoding = [System.Text.Encoding]::UTF8',
-      '  [Console]::WriteLine($dialog.SelectedPath)',
-      '}',
-    ].join('; ')
-    const result = await run('powershell.exe', ['-NoProfile', '-STA', '-Command', script], signal)
-    return outputPath(result.stdout)
-  }
-
-  if (platform === 'linux') {
-    try {
-      const result = await run('zenity', [
-        '--file-selection', '--directory', '--title=Select Workspace Directory',
-      ], signal)
-      return outputPath(result.stdout)
-    } catch (error: unknown) {
-      rethrowIfAborted(signal, error)
-      if (errorCode(error) === 1) return null
-      if (!isMissingCommand(error)) throw error
-    }
-
-    try {
-      const result = await run('kdialog', [
-        '--getexistingdirectory', '.', '--title', 'Select Workspace Directory',
-      ], signal)
-      return outputPath(result.stdout)
-    } catch (error: unknown) {
-      rethrowIfAborted(signal, error)
-      if (errorCode(error) === 1) return null
-      if (isMissingCommand(error)) {
-        throw new Error('no supported native directory picker found (install zenity or kdialog)')
-      }
-      throw error
-    }
-  }
-
-  throw new Error(`native directory picker is unsupported on ${platform}`)
-}