dsh-ptc-plus 0.5.0 → 0.5.1

package/README.en.md

@@ -37,6 +37,8 @@ dsh plugin --profile <profile> add dsh-ptc-plus
 
 Replace `<profile>` with your profile name, restart DSH, and select **PTC mode** in the session. Continuous computation, call tolerance, and global bindings are on by default. To upgrade, run `dsh plugin --profile <profile> add dsh-ptc-plus@latest` and restart that Host; see the [installation guide](docs/installation.md) for other installation methods, Desktop, the local development launcher, and troubleshooting.
 
+The plugin declares `engines.dsh: "*"` for the Host's compatibility preflight; public capability checks and packed tests against the latest official release verify compatibility.
+
 The session shows a **REPL** tab, and wide screens show a **PTC Plus** header indicator. The sparkle button beside the composer opens the global binding menu, the session capability workbench, and **PTC Plus settings**; **Plugins → Installed → dsh-ptc-plus → Configure** in the sidebar is the same configuration.
 
 ## Feature overview
@@ -149,7 +151,7 @@ The settings window and the sidebar plugin configuration page are the same confi
 | --- | --- | --- |
 | Plugin switch | PTC Plus title switch | Enable or disable PTC Plus |
 | Core workspace | REPL syntax | Allow same-name revisions or choose name protection |
-| Core workspace | State and recovery | Restart recovery, contextual tips, and their frequency |
+| Core workspace | State and recovery | Restart recovery, official REPL ownership, contextual tips, and their frequency |
 | Extensions and tolerance | Tool extensions | Global bindings and their management entry, official Cordis tool integration |
 | Extensions and tolerance | Tool call tolerance | Missing call summaries and identifiable misplaced native-tool calls |
 | Interface and resources | Interface display | Enhanced tool cards, the REPL tab, and the sparkle shortcut |
@@ -160,12 +162,18 @@ Everyday computation features are on by default, and **Cordis development tools
 
 Capabilities and context is an experimental group, off by default. It selects availability and disclosure for Skills, tools, and MCP capabilities by category, source, or item, and it also covers Initial prompt, Prompt recovery, Output excerpts, and Usage statistics; the switch beside its title pauses the whole group while keeping every choice, and changes apply to new sessions or to a session after an explicit refresh. The sparkle menu also opens the session capability workbench, which views and adjusts the current session's capabilities by category, source, and state: edits live in one draft that you can apply to this session only or save as the global default. See the [configuration reference](docs/runtime-reference.md#configuration) for fields, defaults, and full limits.
 
+Before a new session starts, capability and global binding changes only update its initial configuration; no change notices are sent or queued. The first request uses the resulting configuration.
+
 The host execution provider must use TypeScript; changing it to another language during a reload withdraws the plugin and reports a diagnostic, and switching back re-enables it.
 
+With DSH's official `executionMode: persistent-in-memory` enabled, **Prioritize the official REPL mode** under State and recovery chooses who owns the PTC session: disabled by default, so PTC Plus owns `run_code`; enabled, the official runtime owns execution and PTC Plus leaves execution, REPL state semantics, and observation to it. The setting has no effect while the official mode is off. Ownership changes take effect immediately and leaving plugin execution disposes its in-memory environment. Official in-memory state follows DSH's Agent/provider lifecycle; changing priority does not guarantee clearing it. Official-mode calls stay outside the plugin's records, so they never count as recoverable state after switching back to the plugin.
+
 ![PTC Plus settings window](assets/ptc-plus-settings-en.png)
 
 ## Value transfer and state recovery
 
+Stopping a background subagent preserves the parent session's REPL state, so calls triggered by its notification can continue using the parent's variables. If the parent session itself is disposed, later calls follow the recovery rules below.
+
 Within the supported range of the plugin's graph IPC, program arguments, results, and recovery records keep `undefined`, BigInt, `NaN`, infinities, sparse arrays, cycles, and shared references, and supported values can be returned directly without writing `JSON.stringify` yourself (it drops object fields containing `undefined`, turns `NaN` and infinities into `null` and `-0` into `0`, and rejects BigInt). Functions, Promises, class instances, Date, Map, and Set are outside that range, and native `tools.*` JSON argument and result contracts do not change; see the [value contract](docs/value-wire.md).
 
 Session state is not permanent memory: after a restart, a runtime reset, or context compaction, only state verifiable from session records whose provenance remains in the model's context is retained, and everything else is discarded with a diagnostic, continuing in an empty environment when necessary. Missing or damaged session records produce an explicit error instead of being treated as a successfully recovered empty session. Recovery neither redispatches recorded native-tool calls nor reverses historical external effects; see the [runtime reference](docs/runtime-reference.md) for its evidence and limits.

package/README.md

@@ -37,6 +37,8 @@ dsh plugin --profile <profile> add dsh-ptc-plus
 
 把 `<profile>` 换成实际 profile 名称，重启 DSH，在会话中选择 **PTC 模式**。连续计算、调用容错和全局绑定默认开启；升级用 `dsh plugin --profile <profile> add dsh-ptc-plus@latest` 再重启宿主，其他安装方式、Desktop、本地开发启动器和故障排查见[安装指南](docs/installation.md)。
 
+插件通过 `engines.dsh: "*"` 接入宿主兼容性预检，按最新官方发行版的公共能力检查与打包测试验证兼容性。
+
 界面默认显示会话里的 **REPL** 页签，宽屏顶部还有 **PTC Plus** 标志。输入框旁的星光按钮打开全局绑定菜单、会话能力工作台和 **PTC Plus 设置**，侧边栏的 **插件 → 已安装 → dsh-ptc-plus → 配置** 是同一套设置。
 
 ## 功能概览
@@ -149,19 +151,23 @@ return capabilities.search({ query: 'read file content', budgetBytes: 8192 })
 | --- | --- | --- |
 | 插件开关 | PTC Plus 标题总开关 | 启用或停用 PTC Plus |
 | 核心工作区 | REPL 语法 | 允许同名修订或选择名称保护 |
-| 核心工作区 | 状态与恢复 | 重启恢复、上下文提示及其频率 |
+| 核心工作区 | 状态与恢复 | 重启恢复、官方 REPL 模式归属、上下文提示及其频率 |
 | 扩展与容错 | 工具扩展 | 全局绑定及其管理入口、官方 Cordis 工具集成 |
 | 扩展与容错 | 调用容错 | 缺失调用摘要、可识别的错位原生工具调用 |
 | 界面与资源 | 界面显示 | 增强工具卡片、REPL 页签和星光快捷入口 |
 | 界面与资源 | 资源限制 | 执行时间、内存和输出预算 |
 | 实验性 | 能力与上下文 | 实验性能力管理（默认关闭）、独立统计、常用集、单项选择和展示预算 |
 
+新会话尚未开始时，调整能力或全局绑定只更新初始配置，不发送或排队发送变更说明；首轮使用调整后的配置。
+
 面向日常计算的功能默认开启，**Cordis 开发工具默认关闭**，要检查或开发 DSH 插件时再打开，详见[集成说明](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md)。
 
 “能力与上下文”是实验性设置，默认关闭。打开后可以按类别、来源和单项选择 Skills、Tools 和 MCP 能力的启停与说明方式，初始提示、提示恢复、输出节选和使用统计也在这里；标题旁的总开关一次暂停整组并保留原有选择，改动对新会话或明确刷新后的会话生效。星光菜单里还有一个会话能力工作台，用来按类别、来源和状态查看、调整当前会话的能力，改动先放进草稿，可以只写进本会话，也可以保存成全局默认。字段、默认值和完整限制见[配置参考](docs/runtime-reference.md#configuration)。
 
 宿主执行 provider 必须使用 TypeScript；热重载换成别的语言时插件会撤出并报出诊断，换回来就重新启用。
 
+开启 DSH 官方的 `executionMode: persistent-in-memory` 后，可以在“状态与恢复”里用**官方 REPL 模式优先**选择谁接管 PTC 会话：默认关闭，`run_code` 由 PTC Plus 接管；开启后由官方运行时接管，PTC Plus 让出执行、REPL 状态语义与观察，官方模式没开启时该设置不生效。切换立即生效，离开插件执行时会释放插件的内存环境；官方内存状态由 DSH 的 Agent/provider 生命周期管理，切换优先设置不保证清空它。官方执行期间的调用不进入插件记录，切回插件后不会当作可恢复状态。
+
 ![PTC Plus 设置窗口](assets/ptc-plus-settings-zh.png)
 
 ## 值传递与状态恢复
@@ -170,6 +176,8 @@ return capabilities.search({ query: 'read file content', budgetBytes: 8192 })
 
 会话状态不是永久内存：重启、执行环境重置或上下文压缩后，只保留能从会话记录验证、且来源仍在模型上下文中的状态，其余会被丢弃并给出提示，必要时从空环境继续当前计算。会话记录本身缺失或损坏时会明确报错，不会被当作成功恢复的空会话。恢复不会重新派发已记录的原生工具调用，也不会撤销历史外部效果，依据和限制见[运行时参考](docs/runtime-reference.md)。
 
+停止后台子代理不会清空父会话的 REPL 状态；通知触发的后续调用可以继续使用父会话的变量。父会话自身释放后，后续调用仍按上述恢复规则继续计算。
+
 ## 使用边界
 
 - **执行权限**：主要面向 `danger-full-access`。代码可以直接访问 Node.js 和操作系统，插件不额外提供安全沙箱；原生工具权限、审批、取消和沙箱策略仍归 DSH。