CherryHQ / CherryHQ/cherry-studio

[Feature]: Agent runtime support for using user's natively installed Pi (loading ~/.pi configuration and extensions)

Open
#20,331 0 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.