[Feature Request] Keep managed and self-managed Pi providers side by side without replacing existing setups

[Astro-Han]

Affected area

Agent runtime / ACP

Problem or workflow pressure

Users with a customized local Pi setup need to preserve their runtime and extensions while trying Lody's built-in Pi. The current “Upgrade Pi providers” action converts eligible registry/pi-acp providers to builtin/pi in place. It preserves the provider ID, name, and environment but changes the launch implementation. The built-in adapter uses a pinned Pi runtime and disables external extension discovery, so preserving configuration fields does not preserve the original behavior.

Custom Providers already support independent ACP commands. However, legacy pi-acp is absent from new-provider discovery, and the provider editor does not allow changing provider type. After migration, restoring the previous integration requires users to reconstruct a configuration. This is a provider-choice and migration-experience problem, not a reason to promise compatibility with every Pi customization.

Desired outcome

Users can keep both “Pi (managed by Lody)” and “Pi (self-managed)” and select either for new sessions. Enabling or updating managed Pi must not replace the self-managed launch configuration or change existing session bindings. The product must explain which configuration is shared and where compatibility ends.

Proposed solution

1. Add rather than replace. Replace the migration card with an “Add built-in Pi” action. Keep the old provider unchanged and create a built-in provider with a separate ID; if a suitable built-in configuration already exists, guide the user to it rather than creating another. Scope the action to the machine explicitly selected by the user. Do not bulk-rewrite legacy providers or automatically change the user's default selection.
2. Reuse existing launch paths. Managed Pi continues through builtin/pi; existing legacy providers retain registry/pi-acp; self-managed setups use customAcp.command/args/env. Add Pi-specific guidance to the existing Custom Provider flow and reuse “Test command,” rather than adding another execution framework. A plain pi command is not an ACP server: a compatible adapter is required.
3. Provide recovery guidance for already-migrated users. Guide users to add a self-managed provider using their original ACP command and necessary environment variables while retaining the managed provider. Without reliable migration provenance, do not offer a guessed automatic rollback, convert built-in configurations in bulk, or automatically rebind historical sessions.
4. Make configuration boundaries explicit. Separate provider IDs isolate integration configuration, not necessarily Pi profiles. Document how to select an independent profile through the provider's PI_CODING_AGENT_DIR environment variable. Do not move, copy, or overwrite existing credentials or configuration files by default. Explain that an independent profile may require authentication and model configuration again.
5. Update the owning contracts. Update the builtin-pi Spec, owning decision records, and provider setup guidance. Revisit the auto-registration condition designed for “one Pi provider plus in-place migration,” so background registration and the new action cannot create duplicate configurations or change user choices.

Acceptance criteria:

• Adding managed Pi leaves the original provider's ID, launch configuration, environment, and existing session bindings unchanged.
• Both providers are selectable and can run concurrently through their respective configured ACP entry points.
• After a managed runtime update, the self-managed provider still launches its original command; the user's self-managed installation is not modified.
• Repeated clicks, retries after failure, and background auto-registration do not create duplicate built-in providers.
• In a controlled test with independent profiles, each integration reads its own configuration. Without explicit isolation, the UI or documentation does not promise complete configuration independence.
• A failing self-managed ACP launch produces an explicit error rather than silently falling back to built-in Pi.

Alternatives or workarounds

Users can manually add a Custom Provider with their previous ACP command today, but must know the correct command, environment, and profile settings. Compatibility with their particular customization still needs verification.

#780 proposes explicitly loading user extensions in managed Pi. That can address some extension workflows, but does not replace the choice to use a self-managed Pi version, fork, or independent adapter. Adding only a Pi executable-path override would not address the built-in adapter's external-extension restriction.

Trade-offs or non-goals

• This issue does not enable arbitrary external extensions in the built-in adapter or promise compatibility with arbitrary Pi forks, TUI plugins, or legacy session IDs.
• Do not automatically migrate credentials, modify the user's Pi installation, or convert native session formats.
• Profile isolation is not a filesystem sandbox. Concurrent sessions modifying the same project should still use separate worktrees.
• Keeping legacy pi-acp available is a compatibility path for existing users, not a commitment to add features to it or permanently maintain two adapters.

Additional context

Source inspection was based on commit 450a007bf47fc405e74a31ef9d886d231642aace. The migration is implemented in packages/shared/src/pi-provider-migration.ts and packages/components/src/components/chat/chat-landing.tsx; launch routing is in apps/cli/src/agent/setting.ts.

The two existing migration tests passed. They confirm the current in-place conversion matches the existing tests, not that the reported user scenario has been reproduced. The reporter's exact version, clicked action, and customization type remain unconfirmed. There is no evidence that the user's local Pi installation was overwritten.

Related: #451, #780.

Before submitting

• I searched the existing issues and did not find a duplicate request.
• This request concerns an open-source component in this repository, not a hosted service, Web or mobile app, account, or billing issue.
• I removed credentials, private source, conversations, prompts, personal data, and other sensitive information.

中文对照

影响范围：Agent runtime / ACP

问题

使用本地定制 Pi 的用户需要保留原有运行时和扩展，同时尝试 Lody 内置 Pi。当前“升级 Pi”会将符合条件的旧 registry/pi-acp Provider 原地转换为 builtin/pi：保留 Provider ID、名称和环境变量，但替换启动实现。内置适配器使用固定版本的 Pi，关闭外部扩展发现，因此保留配置字段不代表保留原有行为。

当前 Custom Provider 已支持独立 ACP 命令，但旧 pi-acp 已从新建目录移除，Provider 编辑界面也不能切换类型。迁移后，恢复原接入方式需要用户自行重建配置。这是接入选择与迁移体验的问题，不应通过宣称内置版兼容所有 Pi 定制来解决。

期望结果

用户可以同时保留“Pi（Lody 管理）”和“Pi（用户自管）”，分别选择用于新会话。启用或更新内置版不替换自管版的启动配置、不改变原有会话绑定，并明确说明配置共享范围与兼容性限制。

方案

1. 添加而非替换。 将现有迁移卡片改为“添加内置 Pi”：保留旧 Provider，创建独立 ID 的内置 Provider；已有合适的内置配置时引导选择，不重复创建。操作仅作用于用户明确选择的目标机器，不批量改写旧 Provider，也不自动切换默认选择。
2. 复用已有接入路径。 内置版继续走 builtin/pi；已有旧 Provider 保留 registry/pi-acp；用户自管版复用 customAcp.command/args/env。在 Pi 接入说明中提供 Custom Provider 引导和现有“Test command”入口，不增加第二套执行框架。普通 pi 命令不是 ACP 服务，必须说明需要兼容的适配器。
3. 提供迁移后的恢复指引。 引导已迁移用户使用原 ACP 命令和必要环境变量新增自管 Provider，保留现有内置 Provider。没有可靠迁移来源记录时，不提供猜测性的自动回退，不批量转换内置配置，不自动重绑历史会话。
4. 明确配置边界。 独立 Provider ID 只隔离接入配置，不保证 Pi profile 独立。提供通过 Provider 环境变量 PI_CODING_AGENT_DIR 指定独立 profile 的说明；默认不移动、复制或覆盖既有认证和配置文件。使用独立 profile 时提示可能需要重新配置认证和模型。
5. 同步现有约定。 更新 builtin-pi Spec、对应决策记录和 Provider 接入说明；重新审视为“单个 Pi Provider + 原地迁移”服务的自动注册条件，避免后台注册与新入口产生重复配置或改写用户选择。

验收标准

• 添加内置 Pi 后，原 Provider 的 ID、启动配置、环境变量和旧会话绑定保持不变。
• 两种 Provider 可同时出现在选择器中，并分别通过各自配置的 ACP 入口并发运行。
• 更新内置运行时后，自管 Provider 仍启动原命令；不修改用户自管程序。
• 重复点击、失败后重试或后台自动注册，不重复创建内置 Provider。
• 使用独立 profile 的受控测试中，两种接入分别读取各自配置；没有设置隔离时，界面或文档不承诺配置完全独立。
• 自管 ACP 启动失败时明确报错，不静默回退到内置 Pi。

替代方案与临时办法

目前可手动新增 Custom Provider 并填写原 ACP 命令，但用户需要知道正确命令、环境变量及 profile 设置，且具体定制兼容性仍需验证。

#780 提议在内置 Pi 中显式加载用户扩展，可以解决部分扩展场景，但不能替代自管 Pi 版本、fork 或独立适配器的接入选择。仅增加 Pi 可执行文件路径也不能解决内置适配器禁用外部扩展的问题。

取舍与非目标

• 不在本 Issue 中开放内置适配器的任意扩展加载，也不承诺任意 Pi fork、TUI 插件或旧会话 ID 兼容。
• 不自动迁移认证、不改写用户 Pi 安装、不转换原生会话格式。
• profile 隔离不等于文件系统沙箱；两个会话修改同一项目时，仍应使用不同 worktree。
• 保留旧 pi-acp 是现有用户的兼容路径，不代表为其新增功能或永久维护两套适配器。

补充信息

基于源码提交 450a007bf47fc405e74a31ef9d886d231642aace 检查。迁移行为由 packages/shared/src/pi-provider-migration.ts 和 packages/components/src/components/chat/chat-landing.tsx 实现；启动分流位于 apps/cli/src/agent/setting.ts。

已有迁移测试 2 项通过，证明当前原地转换行为符合现有测试，并非证明用户现场已复现。尚未确认反馈者的具体版本、点击入口和定制方式，也没有证据证明本地 Pi 安装被覆盖。

相关：#451、#780。

提交前确认

• 已搜索现有 Issue，未发现重复请求。
• 请求涉及本仓库开源组件，而非托管服务、Web 或移动应用、账号或计费问题。
• 已移除凭据、私有源码、对话、提示词、个人信息及其他敏感信息。