Proposal: Workspace Provider API v1 for credential-free remote workspaces

[trrrrrryg]

Workspace Provider API v1 — bilingual design proposal / 工作区提供程序 API v1 双语设计提案

English and 中文 — every section is presented in both languages. This is a community design proposal, not an official DSH feature or an external pull request.

英文与中文对照——每一节均提供双语说明。本讨论是社区设计提案，不代表 DSH 官方功能，也不是外部 Pull Request。

1. Background / 背景

English. I am building a community plugin, DSH SSH Forge, that lets a DSH workspace refer to a remote directory. The plugin is responsible for connection setup and credential storage. This proposal asks only for a small, credential-free DSH Core extension point for workspace identity and Agent execution routing.

中文。 我正在开发社区插件 DSH SSH Forge，让 DSH 工作区可以指向服务器目录。连接建立与凭据存储均由插件负责；本提案仅讨论一个小而无凭据的 DSH Core 扩展点，用于表达工作区身份并路由 Agent 执行。

The contribution guide currently does not accept external pull requests, so I am seeking maintainer and community feedback here before narrowing any implementation.

当前贡献说明暂不接收外部 Pull Request，因此我先在此征求维护者与社区意见，再收敛后续实现。

2. Problem to solve / 要解决的问题

English. A UI can display a remote directory, but that alone does not ensure that Agent file tools, command tools, and resumed sessions operate on the selected server. DSH needs an explicit execution target so that a remote POSIX path can never be silently interpreted as a Host-local path.

中文。 界面能够展示服务器目录，并不代表 Agent 的文件工具、命令工具和恢复后的会话一定会在该服务器运行。DSH 需要一个明确的执行目标，确保远端 POSIX 路径不会被静默地当作 Host 本机路径。

3. Proposed minimal contract / 最小接口提案

Persist only an identity with no secret material:

只持久化不含任何密钥或令牌的目标身份：

type WorkspaceTarget =
  | { kind: 'local'; path: string }
  | {
      kind: 'remote'
      providerId: string
      connectionId: string
      path: string
      displayHost: string
    }

English. A plugin registers a WorkspaceProvider. It resolves a target, reports connection status, and creates an Agent-scoped execution world containing filesystem and subprocess adapters. DSH Core never receives a password, private-key content, or authentication token.

中文。 插件注册 WorkspaceProvider，由其解析目标、报告连接状态，并创建仅绑定到该 Agent 的执行世界，其中包括文件系统与子进程适配器。DSH Core 永远不接收密码、私钥内容或认证令牌。

4. Required safety and compatibility rules / 必须满足的安全与兼容规则

1. Fail closed / 失败关闭

   • English: If the provider is missing, disconnected, replaced, unbound, or mismatched, the operation must fail. It must never fall back to the Host filesystem or subprocess.
   • 中文： Provider 缺失、断联、被热替换、未绑定或目标不匹配时，操作必须失败；绝不能回退到 Host 本地文件系统或子进程。

2. Versioned session metadata / 会话元数据版本化

   • English: Adding workspaceTarget changes durable session meaning. Older Hosts must reject the new format instead of treating /root or another remote absolute path as local.
   • 中文： workspaceTarget 会改变持久化会话的解释方式。旧 Host 必须拒绝新格式，而不能把 /root 等远端绝对路径误当成本地目录。

3. Capability inheritance / 能力继承

   • English: Until subagents, forks, LSP, terminals, and every execution consumer preserve the same remote execution world, these capabilities must be disabled for remote Agents. They must not silently become Host-local.
   • 中文： 在子 Agent、分叉会话、LSP、终端及所有执行消费者都能继承同一远端执行世界之前，远端 Agent 必须禁用这些能力，不能悄然转成本机执行。

4. Plugin-owned credentials / 插件持有凭据

   • English: A provider may use an OS credential store or SSH Agent, but credentials must remain outside Workspace, Session, RPC payloads, event logs, and model-visible context.
   • 中文： Provider 可使用操作系统凭据库或 SSH Agent，但凭据必须始终位于 Workspace、Session、RPC 载荷、事件日志和模型可见上下文之外。

5. Explicit version negotiation / 显式版本协商

   • English: Provider registration should declare compatible API versions. An incompatible provider must be rejected during registration.
   • 中文： Provider 注册时应声明兼容的 API 版本；不兼容的 Provider 必须在注册阶段被拒绝。

5. Suggested phased delivery / 建议的分阶段交付

1. English: Define the versioned, credential-free provider contract and a fake-provider test fixture. Do not expose remote-workspace creation yet.
   中文： 定义版本化、无凭据的 Provider 合同并提供假 Provider 测试夹具；此阶段暂不开放远端工作区创建入口。

2. English: Add complete fail-closed routing for every execution consumer, including session resume and subagent lifecycle.
   中文： 为全部执行消费者加入完整的失败关闭路由，包括会话恢复和子 Agent 生命周期。

3. English: Add Host API and Desktop/Web UI projections only after keyless assembled tests prove the execution seam.
   中文： 仅在无密钥的集成测试证明执行边界可靠后，再加入 Host API 以及 Desktop/Web UI 投影。

6. Questions for maintainers / 想请维护者确认的问题

• English: Should this live under workspace, or be modeled as an Agent execution target separate from workspace identity?
  中文： 该能力应归属 workspace，还是应建模为独立于工作区身份的 Agent 执行目标？
• English: Which plugin/service registration mechanism should own provider lifecycle and API-version negotiation?
  中文： 应由哪一种插件/服务注册机制管理 Provider 生命周期和 API 版本协商？
• English: Is there a preferred Agent-scoped service-substitution pattern for filesystem and subprocess adapters?
  中文： 对文件系统和子进程适配器，是否已有推荐的 Agent 作用域服务替换模式？
• English: Would a fake provider plus no-secret integration snapshots be useful as the first design artifact?
  中文： 将假 Provider 与无密钥集成快照作为首个设计产物是否合适？

7. UI reference — Remote Connections top-level settings page / 界面参考——远程连接一级设置页

English. This anonymized reference shows the intended top-level settings entry: connection management is separated from credentials, workspace-provider availability is visible, and server directory access is presented as an explicit capability.

中文。 下图为已脱敏的一级设置页参考：连接管理与凭据分离；工作区 Provider 的可用状态清晰可见；服务器目录访问被呈现为一项显式能力。

Reference image only / 仅作界面参考：connection details are anonymized; no server address, credential, private-key content, or local key path is shown. / 连接详情已脱敏，不展示服务器地址、凭据、私钥内容或本地密钥路径。

8. Scope boundary / 范围边界

English. I will keep the SSH-specific implementation in the community plugin. I will not submit the current broad implementation as a pull request. Feedback on the contract, security boundary, and delivery sequence is welcome.

中文。 SSH 特定实现将继续保留在社区插件中；当前大范围实现不会作为 Pull Request 提交。欢迎就接口合同、安全边界和交付顺序提出建议。