CherryHQ / CherryHQ/cherry-studio
[Feature]: Agent runtime support for using user's natively installed Pi (loading ~/.pi configuration and extensions)
- Dominant language
- TypeScript
- Stars
- 51.8k
- Forks
- 5k
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 600
Description
> This issue was translated automatically.
### Issue Checklist
- [x] I understand that issues are for reporting problems and requesting features, not for off-topic comments, and I will provide as much detail as possible to help resolve the issue.
- [x] I have checked the pinned issues and searched through the existing [open issues](https://github.com/CherryHQ/cherry-studio/issues), [closed issues](https://github.com/CherryHQ/cherry-studio/issues?q=is%3Aissue%20state%3Aclosed), and [discussions](https://github.com/CherryHQ/cherry-studio/discussions) and did not find a similar suggestion.
- [x] I have provided a short and descriptive title so that developers can quickly understand the issue when browsing the issue list, rather than vague titles like "A suggestion" or "Stuck."
- [x] The latest version of Cherry Studio does not include the feature I am suggesting.
### Platform
macOS
### Version
v2.0.14
### Is your feature request related to an existing issue?
Cherry Studio's Agent runtime runs Pi as a built-in npm dependency (@earendil-works/pi-coding-agent) within the main process, and deliberately replaces Pi's entire disk configuration layer with Cherry-managed in-memory objects. This causes a complete disconnect between the user's locally installed native Pi and the agent:
1. Extensions cannot be loaded: In `src/main/ai/runtime/pi/PiRuntimeConnection.ts`, `DefaultResourceLoader` is constructed with `noExtensions: true`, so extensions written by users under `~/.pi/agent/extensions` are never discovered or loaded (the Pi SDK itself supports extensions, and Cherry itself injects two built-in extensions via `extensionFactories`).
2. Configuration does not take effect: `agentDir` points to Cherry's application data directory instead of `~/.pi/agent`; `SettingsManager`/`AuthStorage`/`ModelRegistry` are all `inMemory()`, so user configurations like `settings.json` are entirely bypassed.
3. Version drift: The built-in Pi version is pinned with the App release (the main branch is currently pinned to 0.80.x, while upstream has reached 0.85.x), and users cannot update independently. Additionally, during 0.80→0.85, Pi's extension API has changed (e.g., `AuthStorage` was replaced by `ModelRuntime`), so extensions written with the new API may be incompatible even if loading is enabled.
The result is: users who have written extensions and configurations for native Pi find nothing works in the Cherry agent, and can only treat Pi as "another non-extensible black box".
### Desired Solution
Provide an explicit switch (such as a setting "Load user Pi configuration and extensions", disabled by default). When enabled:
1. `agentDir` points to the user's actual `~/.pi/agent`, `noExtensions` is set to `false`, allowing disk-based user extensions to load normally;
2. After `resourceLoader.reload()`, collect registered tool names from extensions (`getExtensions().extensions[].tools`) and merge them into the `createAgentSession` tools whitelist, allowing them to pass through Cherry's existing approval gates (`approvalExtension` hooks into the generic `tool_call` event, naturally covering this);
3. Preserve Cherry's in-memory injection management for models/credentials (`AuthStorage`/`ModelRegistry` not persisted to disk), avoiding conflicts with Cherry's Provider system;
4. Simultaneously upgrade the built-in `pi-coding-agent` / `pi-ai` dependencies to the latest stable upstream version, and verify whether custom patches under `patches/` are still needed (some fixes have been merged upstream).
Security considerations are understandable (extensions are arbitrary JS running in the main process), so the suggestion is: disabled by default + clear trust boundary warning when enabled; extension load failures should only be logged, not fatal.
### Alternative Solutions
- Spawn local `pi` CLI subprocess + JSON event stream: This is a massive change and would lose in-process control points (per-tool approval, per-request OAuth credential injection, MCP bridging, compaction events), not worth it;
- The existing Code CLI feature does support native pi, but that's a separate entry point and doesn't cover the agent chat runtime;
- Runtime dynamic import of user-installed pi package: Feasible but would be continuously chased by version drift, better to just upgrade the built-in dependencies.
### Additional Information
I have verified the feasibility of the above "desired solution" in my personal fork: upgraded `pi-coding-agent`/`pi-ai` to 0.85.1 (removed coding-agent patches that were merged upstream, remade pi-ai patches), adapted to the `AuthStorage`→`ModelRuntime` API refactoring, and implemented the `agent.pi.load_user_extensions` switch (`agentDir`/`noExtensions`/extension tool whitelist collection/included in connection signature). All 253 tests in `src/main/ai/runtime/pi` pass, typecheck is clean. Core changes are concentrated in the `DefaultResourceLoader` constructor in `PiRuntimeConnection.ts`, with minimal intrusion surface.
Related code:
- `src/main/ai/runtime/pi/PiRuntimeConnection.ts` (`noExtensions: true`, `agentDir`, `inMemory` configuration layer)
- `src/main/ai/runtime/pi/piSdk.ts` (SDK's only loading entry point)
- `patches/@earendil-works__pi-*.patch` (custom patches for built-in version)
---
Original Content
### Issue Checklist
- [x] I understand that issues are for reporting problems and requesting features, not for off-topic comments, and I will provide as much detail as possible to help resolve the issue.
- [x] I have checked the pinned issues and searched through the existing [open issues](https://github.com/CherryHQ/cherry-studio/issues), [closed issues](https://github.com/CherryHQ/cherry-studio/issues?q=is%3Aissue%20state%3Aclosed), and [discussions](https://github.com/CherryHQ/cherry-studio/discussions) and did not find a similar suggestion.
- [x] I have provided a short and descriptive title so that developers can quickly understand the issue when browsing the issue list, rather than vague titles like "A suggestion" or "Stuck."
- [x] The latest version of Cherry Studio does not include the feature I am suggesting.
### Platform
macOS
### Version
v2.0.14
### Is your feature request related to an existing issue?
Cherry Studio 的智能体(Agent)运行时将 Pi 作为内置 npm 依赖(@earendil-works/pi-coding-agent)在主进程内运行,并且刻意把 Pi 的整个磁盘配置层替换为 Cherry 托管的内存对象。这导致用户本地安装的原生 Pi 与智能体完全脱节:
1. 扩展无法加载:src/main/ai/runtime/pi/PiRuntimeConnection.ts 中 DefaultResourceLoader 以 noExtensions: true 构造,用户在 ~/.pi/agent/extensions 下编写的扩展永远不会被发现和加载(Pi SDK 本身支持扩展,Cherry 自己就通过 extensionFactories 注入了两个内置扩展)。
2. 配置不生效:agentDir 指向 Cherry 应用数据目录而非 ~/.pi/agent;SettingsManager/AuthStorage/ModelRegistry 全部 inMemory(),用户的 settings.json 等配置被整体绕过。
3. 版本漂移:内置 Pi 版本随 App 发布钉死(main 分支目前钉 0.80.x,上游已到 0.85.x),用户无法独立更新;且 0.80→0.85 期间 Pi 的扩展 API 已有变化(如 AuthStorage 被 ModelRuntime 取代),用户按新版 API 写的扩展即使打开加载也可能不兼容。
结果就是:为原生 Pi 写好扩展和配置的用户,在 Cherry 智能体里一切都不生效,只能把 Pi 当作"另一个不可扩展的黑盒"。
### Desired Solution
提供一个显式开关(如设置项"加载用户 Pi 配置与扩展",默认关闭),开启后:
1. agentDir 指向用户真实的 ~/.pi/agent,noExtensions 置为 false,让磁盘上的用户扩展正常加载;
2. 在 resourceLoader.reload() 后收集扩展注册的工具名(getExtensions().extensions[].tools),并入 createAgentSession 的 tools 白名单,使其穿过 Cherry 现有的审批门控(approvalExtension 挂在通用 tool_call 事件上,天然覆盖);
3. 保留 Cherry 对模型/凭证的内存注入托管(AuthStorage/ModelRegistry 不落盘),避免与 Cherry 的 Provider 体系冲突;
4. 同步将内置 pi-coding-agent / pi-ai 依赖升级到上游最新稳定版,并核对 patches/ 下的自定义补丁是否仍需要(部分修复已上游合入)。
安全考量可以理解(扩展是运行在主进程内的任意 JS),因此建议:默认关闭 + 开启时明确提示信任边界;扩展加载失败仅记日志不致命。
### Alternative Solutions
- spawn 本地 pi CLI 子进程 + JSON 事件流:改动巨大,且会丢失进程内控制点(逐次工具审批、按请求注入 OAuth 凭证、MCP 桥接、compaction 事件),不划算;
- 现有 Code CLI 功能确实支持原生 pi,但那是独立入口,不覆盖智能体聊天运行时;
- 运行时动态 import 用户安装的 pi 包:可行但被版本漂移持续追着打,不如直接升级内置依赖。
### Additional Information
已在个人 fork 中验证上述"期望方案"的可行性:升级 pi-coding-agent/pi-ai 至 0.85.1(移除已上游合入的 coding-agent 补丁、重制 pi-ai 补丁),适配 AuthStorage→ModelRuntime 的 API 重构,并实现 agent.pi.load_user_extensions 开关(agentDir/noExtensions/扩展工具白名单收集/纳入连接签名),src/main/ai/runtime/pi 全部 253 个测试通过、typecheck 干净。核心改动集中在 PiRuntimeConnection.ts 的 DefaultResourceLoader 构造处,侵入面很小。
相关代码:
- src/main/ai/runtime/pi/PiRuntimeConnection.ts(noExtensions: true、agentDir、inMemory 配置层)
- src/main/ai/runtime/pi/piSdk.ts(SDK 唯一加载入口)
- patches/@earendil-works__pi-*.patch(内置版本的自定义补丁)
Contributor guide
Research direction
Start with src/main/ai/runtime/pi/PiRuntimeConnection.ts and src/main/ai/runtime/pi/piSdk.ts to trace DefaultResourceLoader and configuration loading, then inspect the related patches under patches/@earendil-works__pi-*.patch. Run the existing src/main/ai/runtime/pi tests and typecheck; done means the opt-in setting loads ~/.pi configuration and extensions without breaking Cherry's provider management or approval flow.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- ai, backend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100