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/client/runtime/src/client/index.ts

@@ -13,7 +13,7 @@ export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
 export { createScope } from './agents/scope.ts'
 export type { AgentScopeHandle } from './agents/scope.ts'
-export { WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
+export { DirectoryBrowseError, WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
 export type { Session } from './sessions/session.ts'
 export type {
   SessionBinding, SessionListState, SessionProvideContribution, SessionProvideDescriptor, SessionSummary,
@@ -21,7 +21,9 @@ export type {
 export type { SessionListPhase } from './sessions/manager.ts'
 export type { WorkspaceListPhase } from './workspaces/manager.ts'
 export type { WorkspaceListState } from './workspaces/service.ts'
-export type { WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
+export type {
+  DirectoryEntry, DirectoryListing, DirectoryPickerKind, WorkspaceId, WorkspaceView,
+} from '@deepseek-ai/dsh-client-connection/client'
 // Runtime owns the snapshot store; web-react only binds it to React.
 export { createSnapshotStore, defineStore, shallowEqual } from './contract/store.ts'
 export type {

packages/client/runtime/src/client/workspaces/service.ts

@@ -2,7 +2,8 @@
 
 import type { Context } from 'cordis'
 import type {
-  IApiClient, RpcError, SessionId, WorkspaceId, WorkspaceView,
+  DirectoryListing, DirectoryPickerKind, IApiClient, RpcError,
+  SessionId, WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
@@ -29,6 +30,14 @@ export class WorkspaceCreateError extends Error {
   }
 }
 
+/** Structured browse failure so the directory browser can branch on Host business codes. */
+export class DirectoryBrowseError extends Error {
+  constructor(readonly rpcError: RpcError) {
+    super(`directory browse failed: ${rpcError.code}: ${rpcError.message}`)
+    this.name = 'DirectoryBrowseError'
+  }
+}
+
 /** Real Workspace object layer and Host actions. */
 export class WorkspacesService {
   /** UI-facing immutable projection; the manager remains wire truth. */
@@ -171,7 +180,7 @@ export class WorkspacesService {
   }
 
   /**
-   * Open the Host's native directory picker.
+   * Open the Host's native directory picker (the `dialog` capability).
    * @returns the selected path, or null when the user cancelled.
    */
   async pickDirectory(): Promise<string | null> {
@@ -182,6 +191,44 @@ export class WorkspacesService {
     return response.result.value.path
   }
 
+  /**
+   * The directory-picking interaction the Host composed — the fact the picker
+   * UI branches on (`dialog` opens the native chooser; `browse` opens the
+   * in-app browser). Read per flow open: one describe round trip, no cache to
+   * go stale across reconnects.
+   * @returns the Host's advertised picker kind.
+   */
+  async directoryPickerKind(): Promise<DirectoryPickerKind> {
+    const response = await this.api.host.describe({})
+    if (!response.result.ok) {
+      throw new Error(`host describe failed: ${response.result.error.message}`)
+    }
+    return response.result.value.directoryPicker
+  }
+
+  /**
+   * List one directory level through the Host's `browse` capability.
+   * @param path - absolute directory to list; absent lists the Host home directory.
+   * @returns the level's listing with breadcrumb ancestry.
+   */
+  async listDirectory(path?: string): Promise<DirectoryListing> {
+    const response = await this.api.host.listDirectory(path === undefined ? {} : { path })
+    if (!response.result.ok) throw new DirectoryBrowseError(response.result.error)
+    return response.result.value
+  }
+
+  /**
+   * Create one child directory through the Host's `browse` capability.
+   * @param path - absolute existing parent directory.
+   * @param name - single non-blank path segment.
+   * @returns the created directory's absolute path.
+   */
+  async createDirectory(path: string, name: string): Promise<string> {
+    const response = await this.api.host.createDirectory({ path, name })
+    if (!response.result.ok) throw new DirectoryBrowseError(response.result.error)
+    return response.result.value.path
+  }
+
   /**
    * Rename a Workspace.
    * @param workspaceId - target workspace.

packages/client/runtime/tests/fake-api.ts

@@ -80,11 +80,22 @@ export class FakeApiClient implements IApiClient {
     payload => Promise.resolve(ok({ selected: { provider: payload.provider, model: payload.model } }))
   onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onCancel: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
-  onDescribe: (payload: unknown) => Promise<RpcResponse<{ version: string; cwd: string; attachedSessions: number }>> =
-    () => Promise.resolve(ok({ version: '0-fake', cwd: '/f', attachedSessions: 0 }))
+  onDescribe: (payload: unknown) => Promise<RpcResponse<{ version: string; cwd: string; attachedSessions: number; directoryPicker: 'dialog' | 'browse' }>> =
+    () => Promise.resolve(ok({ version: '0-fake', cwd: '/f', attachedSessions: 0, directoryPicker: 'browse' as const }))
   onPickDirectory: (payload: unknown) => Promise<RpcResponse<{ path: string | null }>> =
     () => Promise.resolve(ok({ path: null }))
 
+  onListDirectory: (payload: unknown) => Promise<RpcResponse<{
+    path: string
+    home: string
+    crumbs: { name: string; path: string; hidden: boolean }[]
+    entries: { name: string; path: string; hidden: boolean }[]
+  }>> =
+    () => Promise.resolve(ok({ path: '/home/fake', home: '/home/fake', crumbs: [{ name: '/', path: '/', hidden: false }], entries: [] }))
+
+  onCreateDirectory: (payload: unknown) => Promise<RpcResponse<{ path: string }>> =
+    () => Promise.resolve(ok({ path: '/home/fake/new' }))
+
   private readonly muxConns: StreamConn<MuxFrame>[] = []
   private readonly hostConns: StreamConn<HostFrame>[] = []
 
@@ -106,6 +117,8 @@ export class FakeApiClient implements IApiClient {
   readonly host: IApiClient['host'] = {
     describe: (payload: unknown) => this.record('host.describe', payload, this.onDescribe(payload)),
     pickDirectory: (payload: unknown) => this.record('host.pickDirectory', payload, this.onPickDirectory(payload)),
+    listDirectory: (payload: unknown) => this.record('host.listDirectory', payload, this.onListDirectory(payload)),
+    createDirectory: (payload: unknown) => this.record('host.createDirectory', payload, this.onCreateDirectory(payload)),
   }
 
   onWorkspaceList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))

packages/client/runtime/tests/workspaces-service.spec.ts

@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest'
 import type { SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
 import { SessionsService } from '../src/client/sessions/service.ts'
 import { WorkspaceManager } from '../src/client/workspaces/manager.ts'
-import { WorkspaceCreateError, WorkspacesService } from '../src/client/workspaces/service.ts'
+import { DirectoryBrowseError, WorkspaceCreateError, WorkspacesService } from '../src/client/workspaces/service.ts'
 import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
 
 const sid = (id: string): SessionId => id as SessionId
@@ -234,6 +234,38 @@ describe('WorkspacesService', () => {
     api.onPickDirectory = () => Promise.resolve(ok({ path: null }))
     await expect(workspaces.pickDirectory()).resolves.toBeNull()
     expect(api.callsOf('host.pickDirectory')).toEqual([{}, {}])
+    api.onPickDirectory = () => Promise.resolve(err({ code: 'internal', message: 'no chooser', details: {} }))
+    await expect(workspaces.pickDirectory()).rejects.toThrow(/no chooser/)
+  })
+
+  it('reads the picker kind from describe per call, failing loud on an unreachable host', async () => {
+    const ctx = new Context()
+    const api = new FakeApiClient()
+    const workspaces = new WorkspacesService(ctx, api, new SessionsService(ctx, api))
+    await expect(workspaces.directoryPickerKind()).resolves.toBe('browse')
+    api.onDescribe = () => Promise.resolve(err({ code: 'internal', message: 'down', details: {} }))
+    await expect(workspaces.directoryPickerKind()).rejects.toThrow(/host describe failed/)
+  })
+
+  it('passes listings and creation through the browse wire, wrapping business failures', async () => {
+    const ctx = new Context()
+    const api = new FakeApiClient()
+    const workspaces = new WorkspacesService(ctx, api, new SessionsService(ctx, api))
+    const listing = { path: '/home/u', home: '/home/u', crumbs: [{ name: '/', path: '/', hidden: false }], entries: [{ name: 'p', path: '/home/u/p', hidden: false }] }
+    api.onListDirectory = () => Promise.resolve(ok(listing))
+    await expect(workspaces.listDirectory()).resolves.toEqual(listing)
+    await expect(workspaces.listDirectory('/home/u')).resolves.toEqual(listing)
+    // The optional path is omitted from the payload, not sent as undefined.
+    expect(api.callsOf('host.listDirectory')).toEqual([{}, { path: '/home/u' }])
+    api.onListDirectory = () => Promise.resolve(err({ code: 'directory-unreadable', message: 'denied', details: { path: '/x' } }))
+    const listFailure = workspaces.listDirectory('/x')
+    await expect(listFailure).rejects.toBeInstanceOf(DirectoryBrowseError)
+    await expect(listFailure).rejects.toMatchObject({ rpcError: { code: 'directory-unreadable' } })
+
+    await expect(workspaces.createDirectory('/home/u', 'fresh')).resolves.toBe('/home/fake/new')
+    expect(api.callsOf('host.createDirectory')).toEqual([{ path: '/home/u', name: 'fresh' }])
+    api.onCreateDirectory = () => Promise.resolve(err({ code: 'directory-exists', message: 'taken', details: { path: '/home/u/fresh' } }))
+    await expect(workspaces.createDirectory('/home/u', 'fresh')).rejects.toMatchObject({ rpcError: { code: 'directory-exists' } })
   })
 
   it('deletes a Workspace or preserves it when the Host rejects deletion', async () => {