@zihanw/pi-forge 0.5.5 → 0.5.7

package/docs/development/roadmap.md

@@ -4,7 +4,17 @@
 
 This file contains forward-looking product work only. Completed capability belongs in the [feature inventory](../reference/features.md), release history in the root [changelog](../../CHANGELOG.md), and completed investigation in the [design archive](../design/README.md).
 
-## Active 0.5.5: session capabilities
+## Active 0.5.7: readable Preview and scrolling release
+
+The accepted UI update adds readable role-colored context, collapsible Tools groups, original-order / safe call-paired result views, and individually disclosed historical tool JSON. Current session and short-screen Preset inspection remain scroll-reachable. The closeout review repaired search coverage and disclosure/reading-state retention, including same-Preset draft updates with an explicitly pending previous preview.
+
+This is a read-only inspection and scrolling release: no provider-context, executable-tool, resource-schema or cache-behavior change. Local full verification and independent fixed-version UI rechecks are complete; the final release commit still follows all [release gates](release.md). OMP compatibility and optional-package work remain independent, not gates for this release. Publishing does not authorize an installed-host upgrade or reload.
+
+## 0.5.6 regression and UI closeout (completed)
+
+0.5.6 delivered leading-System preservation, Preset/Profile edit protection, Capability conflict preflight, auto-profile diagnostics, whole-row disabled styling and browser-local pane resizing. See the [changelog](../../CHANGELOG.md) for the published patch history.
+
+## 0.5.5 capability baseline (completed)
 
 Implementation is authorized under the [accepted capability design](../design/pi-forge-system-update-design-notes.md) and [lean-plan amendment](../design/architecture-0.5.md#accepted-055-amendment-session-capabilities). Pi 0.86 is released; the old upstream-blocked thin-sections proposal is superseded.
 
@@ -15,7 +25,7 @@ One active lane at a time:
 3. **Session observability & activity panel (implemented):** derived multi-capability state, actual selected tools, delivery status (`none`, `pending`, `prepared`), presentation indicators, and guarded human disable/reset; real SDK summarizer-input characterization.
 4. **Preset authorization & restricted Agent control (implemented):** live Preset binding schema (`capabilities`), opt-in `modelCallable: true`, and model-callable `forge_capability` tool with fixed list/status/enable/disable schema; per-call trust, binding identity, authorization, and tool policy checks; strict user-vs-agent ownership.
 5. **Capabilities library CRUD, Preset binding editor, and guarded human Web activation picker (delivered in functional source):** dedicated **Capabilities** surface for project/global capability CRUD with `sourceRevision` stale-save guards; dedicated peer Capability bindings editor with finite overrides and live source-effective preview; guarded human Web activation picker (`GET /api/capability-state/available`, `POST /api/capability-state/enable`) with pre-activation preview and session guard plus content fingerprint validation. Parent safeguards enforce raw source/revision coherence, external new bindings stale-save detection, and lifecycle/re-entry fences (`disposed`, `lifecycleRevision`, `sameContext`).
-6. **Main-package 0.5.5 release closeout:** The accepted UI and local full verification closed out on 2026-09-24 (`89c6ba2`); bilingual README B and reviewed continuous media are adopted. UI scope is frozen except for regressions/release blockers. The main package is versioned 0.5.5; publication requires the exact-commit CI and packed-install gates in the [release process](release.md). No paid provider matrix is implied. The optional package and runtime have independent unfinished release work and are not a main-package gate. Repo dev SDK remains pinned to 0.87.0 with peer `>=0.87.0 <0.88.0` (no dual 0.86 support claim).
+6. **Main-package 0.5.5 release closeout:** The accepted UI and local full verification closed out on 2026-09-24 (`89c6ba2`); bilingual README B and reviewed continuous media are adopted. UI scope is frozen except for regressions/release blockers. The main package 0.5.5 was published; subsequent patches retain the exact-commit CI and packed-install gates in the [release process](release.md). No paid provider matrix is implied. The optional package and runtime have independent unfinished release work and are not a main-package gate. Repo dev SDK remains pinned to 0.87.0 with peer `>=0.87.0 <0.88.0` (no dual 0.86 support claim).
 
 Existing README and optional Pet active-state changes are preserved. No host upgrade, reload or publication follows implicitly from local feature development. Foundation tests are not proof of live 0.5.5 behavior.
 

package/docs/guides/web-editor.md

@@ -55,20 +55,37 @@ The Preset workspace provides:
 The resource header identifies the Preset being edited separately from whether it is active in the session. The global Session capabilities strip stays available when switching surfaces. Opening **Preset properties**, item properties, rule cards, or binding details does not modify the draft. Preset properties now opens from the resource header without pushing the editor down; its field edits remain in the same Preset draft until Save. Global Session capabilities retains a compact summary and opens the non-modal **Current session** workspace, separate from the edited resource. Effective tools, instruction excerpts, active capabilities and activation controls come first; full instruction bodies, session identity and transport details are expandable. Trust/stale/error and pending/prepared warnings remain visible. Preset status feedback sits in the footer; its Disable action still targets the active Preset, not the selected draft.
 
 - **Stack:** Rows show a name/on-off control and one summary line, such as `user · report` or `slot · chat-history`. Full identity remains available in tooltips and **Properties**, including Copy ID. Role and slot selection sit beside Properties; content follows directly. Rows support Enter/Space selection and dragging. A quiet, direct delete button remains in the item header with confirmation. Slot option forms size to their contents rather than stretching their rows.
+- **Row state and pane widths:** Disabled rows use a neutral background, muted text and gray side markers; a thin selection outline means editing, not enabling. Drag the right edge of the Presets or Stack items pane to resize it. Double-click or press Enter on the separator to restore its default; arrow keys adjust it, and Escape cancels an active drag. Width preferences stay in this browser origin, never in Preset JSON, and do not dirty or save a draft. Smaller windows temporarily constrain widths to leave editing room; narrow screens retain the stacked layout.
 - **Regex:** Scan rule names, enable state, stage/effect, and pattern excerpts before expanding a rule. Pattern/replacement editing stays prominent; frequency, targets, roles, and limits are under the rule's advanced section. A dashed list-end entry adds and focuses a rule. Rule/binding removal is confirmed and remains a draft change; use the Preset's **Save** action to persist changes.
 - **Policy:** Permission ceiling and default tools are separate cards. Literal/wildcard editing is advanced; skill-list visibility has its own section and is not an execution sandbox.
 - **Preview / Draft diff / Run diff:** Preview is a separate workspace toggle: opening, closing, or changing editor tabs preserves the current editing page. The boundary chevron widens the sidebar; wide mode offers separate shrink and focus buttons. Leaving focus restores the previous nonfocused layout and keeps the inspection tab, without replacing the draft. Choosing another editing section while focused reveals that editor and retains the dock. The panel initially uses the sidebar. Switching Preview, Draft diff, or Run diff changes only its content and preserves the current width and focus state; focused reading is entered explicitly. Narrow windows stack work areas instead of squeezing four columns; focused reading hides the editor until you return or choose an editing section. Draft diff compares draft compilation with the saved definition; Run diff compares captured provider-turn snapshots. Inspection itself does not send a model request or establish cache hits.
 
-Profile editing groups Provider/Model and Thinking/Preset together; immutable identity appears in the heading. Profile and Capability creation still explicitly choose ID and scope. The Advanced Preset tab places editable parameters before the collapsed extension reference catalog. Preview tool details are expandable; section statistics remain available on section-title tooltips.
+Profile editing groups Provider/Model and Thinking/Preset together; immutable identity appears in the heading. Profile and Capability creation still explicitly choose ID and scope. The Advanced Preset tab places editable parameters before the collapsed extension reference catalog. Preview tool details are expandable; section statistics remain available under **Source**.
 
 Contributed **Settings** pages auto-save and show pending/saving/saved/error feedback. Failed edits remain in the form. Presets, Capabilities, and Profiles retain their explicit save controls.
 
+### Reading Preview and tool results
+
+Preview and Current session use readable excerpts with teal user / blue assistant roles. **Tools** groups start expanded; individual calls and results start as single lines. Fold a group to keep just its call/result counts and explicit failures. Groups cover only uninterrupted tools belonging to one assistant message; intervening messages or instructions stay visible. Missing, conflicting or ambiguous call IDs are not guessed. A uniquely matched file result can show the filename from its actual call arguments.
+
+**Results → Original order** is the default. **Pair with calls** places uniquely associated returns beside their calls only within a safe continuous tool interval. Cross-message results and unassociated-result barriers remain in place. This is display pairing, not a timeline or claim about parallel execution; the position markers always refer to the original projection. These view controls do not modify the Preset, provider context or executable tools. Choices are local to the open inspector, not persisted resource settings.
+
+Search examines complete message text, roles, source labels, tool names/call IDs, named System section keys and historical declaration JSON. Matching groups, text and declarations open temporarily; clearing search restores prior disclosure choices and reading positions. **Full text** expands the inspection text; **Source** exposes provenance and existing text estimates. Named System sections distinguish setting, setting empty, and removal; historical tool declarations remain separate from currently selected tools. The existing estimates still describe the compiler's text projection, not full tool schemas, structured arguments or media.
+
+**Historical transcript tool declarations** keep each added tool collapsed to one line: name, an excerpt of its real description, and a count when the schema explicitly lists top-level properties. This is a declared-property count, not inferred arity through references/composites; an unknown schema does not mean zero arguments. Open a tool to inspect or copy its complete Preview declaration JSON (name, description and parameters when present). Removed declarations retain their names only; no missing schema is reconstructed. These historical records do not select executable tools.
+
+Editing within the same Preset keeps inspection choices and unchanged tool reading positions. While the new draft compiles, the previous preview is explicitly marked pending and its inspection controls are paused. A real resource switch still resets local inspection state. On short narrow screens the Preset shell scrolls as needed so headers cannot squeeze the editor/inspection dock to zero height.
+
+**Copy report** retains the compiler text report. Copy a tool row for its complete displayed parameters/output. Structured argument JSON is a representation of the compiled object, not raw provider-wire bytes; images and unsupported content parts have explicit placeholders. Text copying is not a complete multimodal export. Folding, pairing and excerpts do not reduce model context, token usage, or establish cache savings. Draft/Run diff and request invalidation retain their existing meanings.
+
 ### Inspecting a Capability's context impact
 
 The **Current session** workspace places capability controls and tools on the left, and the session projection on the right (stacked on narrow screens). It shows current effective tools and a short excerpt of each active instruction snapshot. A successful Enable/Disable/Reset in this browser also shows the observed tool additions/removals; this is not a persistent history. A Capability's configured tool adjustments are labeled separately: overlapping Capabilities can produce no net tool change.
 
 **Locate in context** keeps the controls visible and highlights related projected update blocks, scrolling to the latest match. Normal updates do not steal the reading position. The workspace inspects the **active saved Preset + current session capabilities**, not whichever Preset is being edited. The Preset editor still supports simultaneous editing and **Preview / Draft diff / Run diff**; switching workspaces preserves its draft, selection, inspection tab and width/focus.
 
+**After switching Presets:** if a turn ran under A and you then activate saved Preset B, this projection updates to B with the existing branch history and current capabilities, without sending a model request. Merely selecting/editing B leaves A active. Earlier A messages and historical declarations can still appear as history; that does not mean B failed to activate. This is a current composition preview, not the last sent request or an exact prediction of the next provider payload. Run diff retains captured requests; Payload shows the capture that was armed, not arbitrary past turns. Capture is at the provider hook and can precede later plugin shaping.
+
 Background status checks are quiet and do not reload the capabilities catalog or disable otherwise usable controls on each poll. Catalog discovery occurs on workspace entry, explicit refresh and relevant mutation follow-up. Returning invalidates late reads from a previous visit without discarding in-flight mutation receipts. Projection reads follow semantic state changes, rather than a second polling loop. During same-branch refresh a labeled previous projection remains visible; stale/untrusted or changed session/branch data is invalidated.
 
 Block numbers apply only to that preview. Native System sections and attributed user-fallback updates retain their actual roles; stopping a Capability does not erase its earlier updates. If no reliable match is visible, the inspector says so rather than guessing. This first iteration requires a trusted session and an active Preset; full event-history browsing is not included.

package/docs/reference/capabilities.md

@@ -44,7 +44,7 @@ Capabilities are JSON files stored in:
   - Direct activation via CLI (`/capability enable <[scope:]id>`) or Web library activation creates an *unbound* session activation.
   - Bound activation via CLI (`/capability enable-bound <id>`) or Web preset binding activation creates a *preset-bound* session activation tied to the active Preset.
 - **Immutable snapshot semantics:** Activation captures an immutable snapshot (`content`, `tools`, `fingerprint`). Modifying or deleting capability files on disk does not mutate already active session snapshots.
-- **Same-Preset reload vs. switching:** Reloading the same Preset retains immutable active snapshots. Switching Presets automatically retires (lifecycle-deactivates) old bound activations while retaining manual and unbound user rules.
+- **Same-Preset reload vs. switching:** Reloading the same Preset retains immutable active snapshots. Switching Presets automatically retires (lifecycle-deactivates) old bound activations while retaining manual and unbound user rules. A switch first checks the surviving capabilities against the target tool policy; a conflict rejects the switch without changing the current selection, tools, or activation events. Disable the conflicting capability before retrying. This does not retroactively modify frozen snapshots when their source files change.
 - **Revocation behavior:** Revoking a binding's authorization (`modelCallable: false`) or removing the binding from the Preset does not retroactively erase active snapshots; human CLI (`/capability disable` or `/capability reset`) or Web panel deactivation is the recovery path.
 - **User vs. Agent ownership and deduplication:** Activations record actor attribution (`user` vs `agent`). Repeated `enable` of an already active capability is idempotent and never performs an automatic owner takeover between user and agent. Takeover requires an explicit deactivation and reactivation cycle.
 
@@ -127,7 +127,7 @@ In the Preset editor, capability bindings are configured under the dedicated pee
   - Arbitrary fields, scripts, or inheritance chains cannot be authored.
 - **Source vs. effective preview:** Side-by-side comparison displays source content/tools alongside effective content/tools, resolved through the same server resolver (`resolveCapabilityBindings`) as runtime activation.
 - **Stale-save guard:** Preset saves enforce a `sourceRevision` check against disk bytes whenever bindings are present or modified, rejecting stale overwrites (409 Conflict), including when external edits added bindings.
-- **Preset save execution impact:** Saving an inactive Preset updates its definition and does not select or activate it. Crucially, saving the currently active Preset immediately reloads and synchronizes its live tool and capability authorization policy in the session, without replacing frozen active capability snapshots.
+- **Preset save execution impact:** Saving an inactive Preset updates its definition and does not select or activate it. Crucially, saving the currently active Preset immediately reloads and synchronizes its live tool and capability authorization policy in the session, without replacing frozen active capability snapshots. If the proposed policy conflicts with those snapshots, saving or overwriting the active Preset is rejected before writing the file; disable the conflicting capability and retry. Editing files outside Forge bypasses this preflight and may require manual recovery after reload.
 
 ## Web session capabilities panel
 

package/docs/zh-CN/guides/web-editor.md

@@ -43,20 +43,37 @@
 资源标题区区分“正在编辑哪份预设”与“它是否已在会话中启用”。切换页面时，全局会话指令摘要仍然可见。打开预设属性、条目属性、规则卡片或绑定详情，不会修改草稿。**预设属性**从资源标题区打开，不再推挤正文；字段修改仍归同一份预设草稿，须显式保存。全局会话指令保留紧凑摘要，操作区进入独立、非模态的**当前会话**工作区，不与编辑中的资源混淆。生效工具、指令摘要、活动能力与启用操作优先；完整指令正文、会话身份和传输详情按需展开；信任／过期／错误和 pending／prepared 警告仍直接可见。预设状态反馈放在页脚；其中的停用仍针对当前生效预设，不是选中的草稿。
 
 - **堆栈：** 列表显示名称／开关与一行摘要，如 `user · report` 或 `slot · chat-history`。完整身份保留在提示与**属性**内，可复制 ID；Role、插槽选择与属性同排，正文紧接其后。支持 Enter／空格选择及拖拽；标题旁保留低强调的直接删除按钮与确认。插槽参数按内容高度排列，不再把几行选项纵向撑满。
+- **关闭状态与栏宽：** 关闭条目整行使用中性背景、弱化文字和灰色侧线；选中的细框只表示正在编辑，不代表开启。拖拽预设栏或堆栈栏右边界可调宽，双击或在分隔线按 Enter 恢复默认，方向键微调，Escape 取消当前拖拽。宽度只记在当前浏览器站点内，不写入预设 JSON、不产生草稿改动或保存请求。窗口变小时临时限制宽度，为正文留空间；窄屏仍采用上下布局。
 - **正则：** 先浏览规则名称、启用状态、阶段／效果与表达式摘要，再展开编辑。表达式与替换正文直接可见，频率、目标、角色和范围限制在高级区。列表末尾的虚线入口添加并聚焦新规则；规则／绑定移除需确认，仍是草稿改动，通过预设的**保存**按钮写入。
 - **策略：** 许可上限与默认工具分成两张卡；字面量／通配符输入收在高级区，技能列表可见性另列，不能当作执行沙箱。
 - **预览／草稿差异／运行差异：** 预览是独立工作区开关，开关或切换编辑页签都保留当前编辑页。边界尖角把侧栏加宽；加宽时分别提供“收窄”和“专注”两个按钮，退出专注恢复之前的非专注布局并保留检查页签，不替换草稿。专注时点击其他编辑页签会露出编辑区并保留预览。面板首次默认侧栏。切换预览、草稿差异或运行差异时只切换内容，保留当前宽度和专注状态；专注阅读需手动进入。窄窗口改为上下布局，避免硬挤四列；专注阅读时暂时隐藏编辑区，返回或选择编辑页签后恢复。草稿差异比较草稿编译结果与已保存定义；运行差异比较捕获的提供商轮次快照。查看本身不请求模型，也不证明缓存命中。
 
-Profile 编辑按 Provider／Model、Thinking／Preset 分组，不可变身份在标题处显示；Profile 与 Capability 创建时仍明确选择 ID 与作用域。预设高级页把可编辑参数放在折叠的扩展参考目录之前。预览工具详情按需展开，段落统计可在标题提示中查看。
+Profile 编辑按 Provider／Model、Thinking／Preset 分组，不可变身份在标题处显示；Profile 与 Capability 创建时仍明确选择 ID 与作用域。预设高级页把可编辑参数放在折叠的扩展参考目录之前。预览工具详情按需展开，段落统计可在**来源**中查看。
 
 插件贡献的**设置**页自动保存，并反馈待保存／保存中／已保存／失败；保存失败的编辑会留在表单。预设、能力与 Profile 仍使用显式保存。
 
+### 阅读 Preview 与工具返回
+
+预览和当前会话使用可读正文摘录，user 青色、assistant 蓝色。琥珀色 **Tools** 组默认展开，组内调用／返回默认单行。收起整组后仍显示调用、返回与明确失败的数量。工具组只覆盖同一助手消息所属的连续工具区间，不隐藏中间的用户消息或指令；缺失、冲突或不唯一的 call ID 不会被猜测配对。唯一匹配的文件返回可显示真实调用参数里的文件名。
+
+**工具返回 → 原始顺序**是默认选项；**按调用配对**仅在安全的连续工具区间内，将唯一关联的返回放到调用旁边，不跨消息或无关联返回的屏障移动。这是展示方式，不是时间线，也不声称工具并行执行；位置编号始终来自原始投影。切换不改预设、提供商上下文或可执行工具，选择仅属于当前打开的检查区，不写入资源配置。
+
+搜索检查完整消息正文、角色、来源标签、工具名／call ID、命名 System 分段的键以及历史声明 JSON；临时展开匹配组、正文与声明，清空后恢复原折叠选择和阅读位置。**全文**展开检查文本，**来源**显示归属及既有文本估算。System 的设置、设空、删除仍明确区分，历史工具声明不混同当前生效工具。现有估算仍针对编译器文本投影，不含完整工具 schema、结构化参数或媒体。
+
+**历史转录工具声明**中，每个新增工具默认折叠成一行：工具名、真实描述摘录，以及 schema 明确列出顶层 properties 时的已声明参数数。它不推断引用／组合 schema 的总参数量；未知不等于零。点开后查看或复制完整预览声明 JSON（有值时包含 name、description、parameters）。移除声明仍只显示已知工具名，不重建不存在的 schema；历史记录不决定当前可执行工具。
+
+同一预设内编辑时，检查选项和未改变的工具阅读位置会保留。新草稿编译期间，上次预览会明确标为待更新，并暂停其检查控件；真正切换资源仍重置局部检查状态。矮窄屏幕下预设工作区可内部滚动，不让标头把编辑／检查区域挤成零高。
+
+**复制报告**保留编译器文本报告；完整显示的工具参数／输出请复制对应工具行。参数 JSON 表示已编译的结构化对象，不是提供商 wire 原始字节；图片及不支持的内容块显示明确占位符，文本复制不等于完整多模态导出。折叠、配对、摘录不会减少模型上下文或 token，也不证明缓存节省；草稿／运行差异与请求失效机制保持原有含义。
+
 ### 检查能力对上下文的影响
 
 **当前会话**工作区左侧是能力与工具控制，右侧是会话投影，窄屏上下排列。当前生效工具和活动指令摘要直接可见。在本页面成功启用、停用或重置后，还显示操作前后实际观测到的工具增减；这不是持久历史。能力**配置的工具调整**另行标注：多个能力重叠作用时，实际工具可能完全不变。
 
 点击**在上下文中定位**，控制区保持可见，右侧高亮关联更新并滚到最近匹配；普通更新不抢阅读位置。这里检查的是**已启用的已保存预设＋当前会话能力**，不是编辑器选中的任意预设。原预设编辑页仍能一边编辑，一边查看**预览／草稿差异／运行差异**；跨工作区保留草稿、选择、检查页签及宽度／专注状态。
 
+**一轮结束后切换预设：**如果这一轮用 A，随后真正启用已保存预设 B，投影会更新为 B 加既有分支历史与当前能力，不必先发一次模型请求；只选中／编辑 B 则仍使用 A。历史里保留 A 的旧消息／工具声明，不代表 B 未生效。这里是当前组成预览，不是上一回已发送请求，也不保证逐字等于下一回 provider payload。运行差异保留已捕获请求；Payload 展示此前已开启捕获的那次，不会追溯任意过去轮次。捕获发生在 provider hook，后续插件仍可能修改最终发送内容。
+
 后台状态检查静默进行，不再每轮读取能力目录或让可用控件闪成禁用态。目录在进入工作区、主动刷新及相关操作后读取；返回时废弃上一轮迟到读取，但不丢弃正在进行的写操作回执。投影由状态的实际变化驱动，不另开轮询；同分支刷新暂保留并明确标注上次投影，过期／不可信或会话／分支切换时使旧结果失效。
 
 块序号只对该次预览有效。原生 System 分段与归属明确的 user fallback 保留实际角色；停用不会抹去此前的更新。没有可靠匹配时会明确提示，不猜测位置。第一版要求可信会话与已启用预设，尚不提供完整的启停事件历史浏览。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zihanw/pi-forge",
-	"version": "0.5.5",
+	"version": "0.5.7",
 	"description": "Pi extension for editable context presets, one-shot agent profiles, tool policy, and request debugging.",
 	"repository": {
 		"type": "git",