dsh-ptc-plus 0.5.0 → 0.5.2

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
@@ -110,6 +112,8 @@ An `accepted: true, scheduled: true` receipt means the edit is scheduled: the en
 | Argument validation reports a missing `description` | Distinguish outer and nested tool arguments and provide correction guidance, saved as a complete message so session history remains loadable |
 | Code fails to parse | Identify the source position; at EOF, suggest a target-bound edit if appending one or two closing delimiters has exactly one validated correction |
 
+When an accepted edit cannot obtain a compute baseline before it runs, the receipt stays a receipt: the revision does not execute, publishes no new binding, and the outer cell keeps its own result, so a restart does not lose what that cell already saved as a durable checkpoint.
+
 The first two behaviors are on by default and can be disabled in settings. Syntax suggestions never execute on their own, and they say nothing about whether the code matches the task's intent. A volatile state cannot be saved as a durable checkpoint, but a rejected save leaves the current variables usable; restore does not undo external effects or change global binding configuration.
 
 ## Project files and tool capabilities
@@ -149,23 +153,31 @@ 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 with their frequency, and the unmeasured-cell reclaim threshold |
 | 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 |
-| Interface and resources | Resource limits | Execution time, memory, and output budgets |
-| Experimental | Capabilities and context | Experimental capability management (off by default), independent statistics, common baseline, individual choices, and presentation budgets |
+| Interface and resources | Resource limits | Execution time, memory, output, sampling, reclamation, and startup limits |
+| Experimental | Capabilities and context | Experimental capability management (off by default), independent statistics, common baseline, individual choices, presentation budgets, and prompt text |
 
 Everyday computation features are on by default, and **Cordis development tools are off by default** so they can be enabled when inspecting or developing DSH plugins; see the [integration notes](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md).
 
 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.
 
+The **Prompt text** tab lists the fixed text the plugin writes for the model: each row names its channel, presence condition, byte count, and read-only reason, and the totals line reports measured bytes, unmeasured slots, and dynamic slots separately. Editable rows are counted per slot and saving writes the configuration; a channel that is not connected yet says so instead of reporting zero bytes as if measured; protocol text, sentences generated from configuration or runtime facts, and the binding notes you wrote yourself stay read-only.
+
+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 → 配置** 是同一套设置。
 
 ## 功能概览
@@ -110,6 +112,8 @@ return receipt
 | 参数校验报告缺少 `description` | 区分外层与嵌套工具参数并给出修正提示；提示以完整消息保存，保持会话历史可加载 |
 | 代码解析失败 | 标出源码位置；若错误在末尾，且追加一到两个闭合符只有一种通过验证的修正，给出绑定原调用的编辑建议 |
 
+被接受的编辑若在真正执行前因为没有取得计算基线而未能运行，收据仍然是收据：修订不执行、不产生新变量，外层 cell 自己的结果照常保存，重启恢复时也不会再因为这次编辑而连带丢掉它已保存为 durable 检查点的状态。
+
 前两项默认开启，可以在设置里关掉。语法建议不会自动执行，也不代表代码符合任务意图。volatile 状态存不成 durable 检查点，但保存被拒绝后当前变量还能接着用；恢复不撤销外部效果，也不改全局绑定配置。
 
 ## 项目文件与工具能力
@@ -149,19 +153,25 @@ return capabilities.search({ query: 'read file content', budgetBytes: 8192 })
 | --- | --- | --- |
 | 插件开关 | PTC Plus 标题总开关 | 启用或停用 PTC Plus |
 | 核心工作区 | REPL 语法 | 允许同名修订或选择名称保护 |
-| 核心工作区 | 状态与恢复 | 重启恢复、上下文提示及其频率 |
+| 核心工作区 | 状态与恢复 | 重启恢复、官方 REPL 模式归属、上下文提示及其频率、未测量 cell 回收阈值 |
 | 扩展与容错 | 工具扩展 | 全局绑定及其管理入口、官方 Cordis 工具集成 |
 | 扩展与容错 | 调用容错 | 缺失调用摘要、可识别的错位原生工具调用 |
 | 界面与资源 | 界面显示 | 增强工具卡片、REPL 页签和星光快捷入口 |
-| 界面与资源 | 资源限制 | 执行时间、内存和输出预算 |
-| 实验性 | 能力与上下文 | 实验性能力管理（默认关闭）、独立统计、常用集、单项选择和展示预算 |
+| 界面与资源 | 资源限制 | 执行时间、内存、输出、采样、回收与启动上限 |
+| 实验性 | 能力与上下文 | 实验性能力管理（默认关闭）、独立统计、常用集、单项选择、展示预算和提示文本 |
+
+新会话尚未开始时，调整能力或全局绑定只更新初始配置，不发送或排队发送变更说明；首轮使用调整后的配置。
 
 面向日常计算的功能默认开启，**Cordis 开发工具默认关闭**，要检查或开发 DSH 插件时再打开，详见[集成说明](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md)。
 
 “能力与上下文”是实验性设置，默认关闭。打开后可以按类别、来源和单项选择 Skills、Tools 和 MCP 能力的启停与说明方式，初始提示、提示恢复、输出节选和使用统计也在这里；标题旁的总开关一次暂停整组并保留原有选择，改动对新会话或明确刷新后的会话生效。星光菜单里还有一个会话能力工作台，用来按类别、来源和状态查看、调整当前会话的能力，改动先放进草稿，可以只写进本会话，也可以保存成全局默认。字段、默认值和完整限制见[配置参考](docs/runtime-reference.md#configuration)。
 
+**提示文本**页签把插件写给模型的固定文本列成清单：每行标注所属通道、存在条件、字节数与只读原因，合计行分别给出已测字节、未测槽和动态槽。可编辑项按槽位计字节，改完保存即写入配置；通道尚未接通时如实显示“通道未接通”，不以 0 字节冒充已测量；协议文本、由配置或运行事实生成的句子，以及你自己写给模型的绑定说明只读展示。
+
 宿主执行 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 +180,8 @@ return capabilities.search({ query: 'read file content', budgetBytes: 8192 })
 
 会话状态不是永久内存：重启、执行环境重置或上下文压缩后，只保留能从会话记录验证、且来源仍在模型上下文中的状态，其余会被丢弃并给出提示，必要时从空环境继续当前计算。会话记录本身缺失或损坏时会明确报错，不会被当作成功恢复的空会话。恢复不会重新派发已记录的原生工具调用，也不会撤销历史外部效果，依据和限制见[运行时参考](docs/runtime-reference.md)。
 
+停止后台子代理不会清空父会话的 REPL 状态；通知触发的后续调用可以继续使用父会话的变量。父会话自身释放后，后续调用仍按上述恢复规则继续计算。
+
 ## 使用边界
 
 - **执行权限**：主要面向 `danger-full-access`。代码可以直接访问 Node.js 和操作系统，插件不额外提供安全沙箱；原生工具权限、审批、取消和沙箱策略仍归 DSH。