@zihanw/pi-forge 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -6,7 +6,85 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 In 0.x development, breaking changes may occur in minor releases and will be explicitly noted.
 
-## [Unreleased]
+## [0.5.1] - 2026-08-23
+
+### Added
+
+- **Cross-platform release CI.** The complete verification surface, including
+  the real-browser editor suite and packed-install smoke, now runs on GitHub's
+  macOS and Windows hosted runners in addition to Linux. Generated TypeScript
+  output and repository text files are pinned to LF so tracked `dist/` checks
+  remain deterministic across operating systems.
+- **UI contribution framework (Lane 1).** Optional packages can now contribute schema-driven configuration pages to the web editor without shipping any UI code into the main package:
+  - New versioned `@zihanw/pi-forge/ui-contribution` entry point: a generic RPC contract over the Pi event bus (`UI_CONTRIBUTION_PORT_VERSION = 1`, with its own version counter separate from the `/subagent` host port) exposing exactly two operations — `listContributions` and `writeValues` — over discover/available/request/reply/unavailable channels. Wire messages carry `hostId` + `generation` binding, version negotiation (`minVersion`/`maxVersion`), bounded discovery timeouts, explicit duplicate-provider failure, and recursive JSON-compatibility validators. All payloads are plain data: no functions, components, or live contexts cross the bus. See the [UI contribution port contract](docs/reference/ui-contribution-port.md).
+  - Web server routes: `GET /api/contrib` returns discovered tab descriptors at page load, and `PUT /api/contrib/<tabId>` proxies submitted values to the contributing package over the bus. The forge side is fully generic and knows nothing about subagents; it never owns the schema, validation, or persistence of contributed tabs (the provider writes its own config files), and with no provider discovered there is no contributed tab and zero cost.
+  - Contribution discovery tolerates provider churn across sessions: providers that appear after startup surface their tabs, departed providers are cleared, and service stop cancels pending discovery.
+  - Data-driven stack-tab registry replaces the stack editor's hardcoded `"policy" | "regex" | "stack"` tab union. Built-in tabs keep their existing hosts (including the legacy imperative items workspace as an ordinary tab), while contributed configuration renders through a self-contained host on a separate top-level **Settings** surface.
+  - Generic schema-form renderer: a self-contained Vue component bridged via the vue-host mechanism, covering deliberately restricted v1 field types — boolean, number, enum, string, plus a record/table shape for keyed per-entry lists. Record identities may use live catalog-backed `keyOptions`, while validation and persistence remain provider-owned. No imperative code was added to `legacy-editor.ts`.
+- **Context diff — per-turn prompt observability (Lane 2).** Consecutive real provider requests are diffed automatically so KV-cache reuse is observable:
+  - Host-neutral pure engine (`src/context-diff.ts`): `TurnSnapshot`/`TurnDiff` shapes, block classification (`same`/`added`/`removed`/`modified`) aligned by stable content-derived keys with positional fallback, and a prefix-walk cache-boundary algorithm that walks matching block hashes and trims the char-level common prefix inside the first mismatched block — no Myers diff. Token figures are chars/4 approximations: relative deltas are accurate, and absolute boundary claims are labeled approx in the UI.
+  - Automatic per-turn capture: every provider request enters a rolling history of the last 20 turns (not just manually armed captures), and each new snapshot is auto-diffed against the previous turn. Block hashes cover role and serialized wire-relevant fields, and request-level sections (tool definitions and similar) participate as blocks so wire changes break the cache boundary faithfully.
+  - `GET /api/context-diff` serves the latest snapshot, the previous-turn diff, and summary rollups (added/removed/net tokens, prefix tokens and ratio).
+  - Preview/diff dock: the preview modal is promoted into a wider right-side panel with three focused views — **Preview** (the live compiled draft), **Draft diff** (the unsaved draft against the saved stack), and **Run diff** (the latest captured provider turn against its predecessor). Diff views hide unchanged blocks by default, show modified blocks in Before/After columns, keep run/cache metadata collapsed until requested, and offer **Focus/Split** controls to use the full editor width without permanently crowding stack editing. The panel is a self-contained Vue component riding Lane 1's data-driven registry; no imperative code was added to `legacy-editor.ts`.
+
+### Fixed
+
+- Preview/Draft/Run diffs now render git-style unified or split line views with old/new line numbers, inline changed spans, and changes-only/three-line/all-line context controls. Chars/4 figures are labeled strictly as estimates. Each captured provider request is correlated with its completed assistant message, so Run metadata shows Pi's actual input/output/cache-read/cache-write usage and a provider-reported cache-hit rate when cache reporting has been observed; otherwise it says the rate is not reported instead of presenting a synthetic zero.
+
+- Schema-driven record settings can now provide catalog-backed `keyOptions`, rendered as a duplicate-safe selector instead of a free-text identity field. UI-contribution handlers may resolve asynchronously, allowing optional packages to refresh host-owned catalogs before returning a schema or validating a write; stale replies are suppressed if that provider generation stops while the handler is pending.
+
+- Selective stack tool allow lists now select from Pi's complete registered tool catalog, so built-in inactive tools such as `grep`, `find`, and `ls` can be activated by a stack and are restored to their prior inactive state when the policy is removed. Allow lists containing `*` remain on the active baseline and do not expand to every inactive tool. The web editor now states the active-vs-registered distinction explicitly.
+- The docked Compiled preview now consumes the editor's current in-memory stack draft, refreshes from actual draft-change notifications, aborts superseded requests, and no longer silently previews the saved disk version while unsaved edits are visible.
+- Plugin configuration no longer mounts inside the stack Preview dock. Contributed pages now live on an independent top-level **Settings** surface, so switching between Stack Preview and Subagent Settings cannot unmount or constrain the settings form.
+- Preview now owns a dedicated DOM mount instead of sharing the legacy stack-tab panel, so saving or selecting another stack cannot leave an active-but-empty dock. Draft changes immediately invalidate visible compiled output, Preview and Run requests both reject superseded responses, and browser tests cover save/selection plus controlled delayed-response races.
+- Settings autosaves are serialized per contribution host and replay the newest full form snapshot after an in-flight write, preventing a slow older PUT from overwriting a newer edit while the UI reports `Saved`. Drafts and save status are retained independently per Settings page during rapid tab switches, while a forge-owned monotonic provider-session key forces clean forms to remount with fresh schema and values after fast provider churn. PUT results are bound to the provider session that received them, so a delayed old-session success retries the preserved draft instead of overwriting the new session. Duplicate contribution IDs are ignored after the first descriptor and Settings button IDs cannot collide with built-in stack tabs.
+- Compiled draft diffs align messages with stable source keys rather than positional `message-<index>` IDs, avoiding cascades of false modifications after insertions. Split Preview and top-level Settings collapse to usable single-column layouts on narrow screens without document-level horizontal overflow.
+- The stack editor now keeps the Project/Global selector attached to **New stack** instead of stretching it across a full row, leaves only primary actions in the toolbar, moves infrequent capture/import/export/delete actions into **More**, and compacts the status, metadata, tab, sidebar, and item-list chrome so editing and Preview/Diff receive substantially more viewport space.
+- The profile editor now keeps the canonical `global:<id>` selector visible in list, summary, edit heading, and save status. Profile JSON continues to store a bare schema ID and same-scope prompt-stack references relatively; their global identity is carried by storage scope and is no longer visually lost in the editor.
+- Context-diff fidelity (architecture review F1–F3/F6 and re-review R1–R4): block hashes are computed from the faithful redacted serialization rather than the lossy capture projection, preserving provider field order for request-level blocks; blocks align by stable unique keys so insertions before existing messages classify correctly; token rounding is conservative and consistent so per-block chips cannot contradict summary totals; and the empty Diff view reflects automatic per-turn capture instead of instructing manual arming.
+- UI-contribution hardening (F4/F5/F7): a partial-patch `writeValues` success no longer clobbers cached descriptor values with stale data; contribution lifecycle handles late-surfacing and departed providers and cancels pending discovery on stop; malformed or oversized `/api/contrib` request bodies return 400/413 instead of surfacing raw validator failures.
+
+## [0.5.0] - 2026-08-21
+
+### Planning
+
+- Replaced the proposed six-phase 0.5.0 plan with the accepted [lean 0.5.0 architecture plan](docs/design/architecture-0.5.md). The original full proposal and Phase-0 evidence are archived under [docs/design/archive/0.5-full-proposal/](docs/design/archive/0.5-full-proposal/README.md) and remain the long-term target.
+- Accepted lean 0.5.0 decisions: complete SillyTavern removal; mutable-variable removal; `forge-v1` with a redesigned pure trusted-extension port; regex `display`/`both` removal while `finalize` is retained under lifecycle-adapter ownership; minimal repositories/codecs with fingerprint and atomic writes deferred; minimal `ForgeWorkspace`; versioned `/subagent` host port with mandatory lifecycle semantics; optional `pi-forge-subagents` package without main-package delegation UI and with dedicated `subagents.json` files; explicit root default, root named extension API, and `/subagent` surfaces.
+
+### Removed
+
+- SillyTavern importer, `/preset import-silly`, its reports, guide, example, and tests are removed. 0.4 is the last supported conversion path.
+- Mutable turn/session variable stores, `pi-forge-variable-state` session entries, set/get/clear variable macros, and the `variables` slot are removed. Static reusable values now live on stack `parameters` in schema v2 or legacy `variables` in v1.
+- Regex `display` and `both` effects are removed and rejected as validation errors; only `outgoing` and `finalize` remain.
+- **Breaking (Lane 4b): legacy package surfaces.** All `@zihanw/pi-forge/src/*` compatibility aliases and the `./examples/*` subpath export are removed. The package root now exports exactly the default Pi extension factory plus `registerMacro`/`registerSlot` and their contract types (`PromptEnvironment`, `PromptRenderHelpers`, macro/slot definition and renderer types, option-schema types, and the trusted project extension API types). `@zihanw/pi-forge/subagent` is the only other entry point. `check-package` enforces the allowlist and forbids legacy aliases.
+
+### Changed
+
+- Prompt compilation uses the `forge-v1` parse/analyze/render engine with a frozen `PromptEnvironment` (`runtime.*`, `parameters.*`, `extensions.*`). Preview, runtime, and subagent preparation share the same compiler entry.
+- `registerMacro` and `registerSlot` move to a pure-contract extension port with immutable `env`, declared dependencies, bounded output, and strict undefined-path errors.
+- Prompt-stack schema v2 introduces immutable `parameters`; unversioned/v1 stacks continue to read through the legacy `variables` field.
+- `finalize` regex remains lifecycle-owned and is excluded from preview, which now reports an informational diagnostic.
+- Legacy 0.4 nested macro syntax (for example `{{upper::x}}`, `{{json::...}}`, `{{iftools::...}}`) is no longer executed by the compiler and must migrate to forge-v1 syntax.
+- Compiler/extension conformance (Lane 1d): custom slots share the pure `{ item, options, env, helpers }` contract with declared `dependencies` and the 16,384-character output limit; `env.extensions` is resolved for slots; a shared dependency analysis and one compilation context keep preview/runtime/subagent consistent; extension values resolve lazily per active branch; nested `{% if %}` and empty-string comparisons are supported.
+- Subagent extraction (Lane 3): the `forge_subagent`/`/forge-agent` execution surface, the web-editor delegation UI, and all subagent configuration reads/writes are removed from the main package and move to the optional `@zihanw/pi-forge-subagents` package, which discovers the active host through the versioned `/subagent` port and owns its own `subagents.json`. Packed-install smoke tests cover main-only and main-plus-optional installs (`check:packed`).
+- Host-neutralization (Lane 3.5): the prompt compiler's rendering and preflight contract is fully host-neutral (capability-driven, no subagent-specific branches), `ForgeWorkspace` is the single owner of resource state and compilation contexts (no second loader/registry path), and subagent documentation/configuration alignment was completed for the optional package split. The packed-install smoke was made portable across checkouts.
+- Forge-native host contract (Lane 4a): the main package no longer depends on `@zihanw/pi-subagent-runtime` at all. `@zihanw/pi-forge/subagent` is now exactly the minimal Forge DTO host contract — host-port wire messages, recursive validators, transport, client/host lifecycle, and Forge-owned canonical fingerprint helpers (byte-compatible with the runtime's `sha256:v1` canonical JSON, pinned by golden vectors). The 0.4 execution contract (request, preflight, plan, response, context budgeting, tool negotiation, and validators) moves to `@zihanw/pi-forge-subagents` with names unchanged, importing portable leaves from the runtime directly. Host-owned preparation no longer synthesizes runtime request/preflight/prompt-runtime artifacts: the workspace resolves the profile and stack from its snapshot, filters the client tool catalog through stack policy, and compiles through the shared compilation context directly. **Breaking:** the package root no longer re-exports subagent contract or host-resolution names (the `/subagent` entry point is the only subagent surface); client-side snapshot validation keeps structural and fingerprint checks while deep profile schema validation remains host-owned.
+- Minimum repositories and codecs (Lane 2a): prompt-stack and agent-profile parse/normalize/validate/serialize are centralized in `src/codecs/`, and reads, writes, and deletes all go through scoped repositories (`src/repositories/`) with containment and symlink checks; the loaders and profile service delegate to the repositories, so domain resources are never read or written directly at the adapter layer. Replacement semantics are unchanged and characterized by tests (no fingerprint conflict or atomic replace yet). Legacy stack migration is a documented byte-preserving exception whose raw IO lives inside the repository.
+- ForgeWorkspace and host port v1 (Lane 2b): a minimal `ForgeWorkspace` snapshot owner (genuinely immutable, deep-frozen snapshots) over the repositories/codecs, plus a versioned `@zihanw/pi-forge/subagent` host-port protocol over the Pi event bus with the three minimal operations (discovery, profile listing, prepare). Mandatory lifecycle semantics are enforced and covered by tests: bounded timeouts, explicit duplicate-host failure, `hostId`+`generation`-bound request/reply so stale/foreign requests are rejected, disposal/`unavailable`, listener cleanup, host-owned prompt preparation (client sends only profile selector + task + backend facts), and recursive JSON-compatible operation validators. The host is wired into the real extension lifecycle via `pi.events` (host can only start after the first snapshot exists, so availability implies a loaded workspace; `reload` honors project trust; disposal runs before subagent teardown; the base system prompt is host-owned and empty for delegated subagents), with integration tests that discover, list, prepare, and observe disposal through the published `/subagent` surface — including that the host is not advertised before any session start. Operation validators are strict and recursive: exact nested field sets, typed enums, plain-object-only JSON compatibility, and unknown-field rejection — so `allowProcess` is the only process fact and no runtime access/limit/execution material crosses.
+
+- Documentation and migration notes (Lane 4d): the [public API policy](docs/reference/public-api.md) was rewritten for the three intentional entry points; the 0.4 subagent adapter contract reference was replaced by the [subagent host port contract](docs/reference/subagent-host-port.md); the [0.5 migration guide](docs/guides/migrating-to-0.5.md) now covers Lanes 1–4 with a [zh-CN translation](docs/zh-CN/guides/migrating-to-0.5.md); README, setup, getting-started, web-editor, features, and configuration docs were aligned with the optional-package split (EN + zh-CN).
+
+- Strengthened the `/subagent` host-port DTO types (code-review follow-up, no wire-behavior change): `ForgeResolveProfileResponse.snapshot`, `ForgePrepareResponse.messages`/`diagnostics`/`profileSnapshot` are no longer `unknown`. New exported types: `ForgeProfileSnapshot`, `ForgeWireAgentProfile`, `ForgeWirePromptStack`, `ForgeDelegationMessage`, `ForgeDelegationDiagnostic`, `ForgePromptDependency`/`ForgePromptDependencyKind`, `ForgeListProfilesResponse`, `ForgeHostWireMessage`, and a generic `ValidationResult<T>`; the recursive validators now return typed data. Runtime validation is byte-compatible with 0.5.0.
+
+### Fixed
+
+- Profile auto-activation now honors project-over-global shadowing: a global `autoActivate` profile whose ID exists in project scope no longer activates, matching `chooseAutoActivateStack` semantics (0.5.x review A1). Regression test covers explicit opt-out and implicit shadowing.
+- The fresh-session startup branch now evaluates auto-activation requests with the same shadow-aware candidacy (A1 follow-up, found by dogfooding): a global `autoActivate` profile shadowed by a same-ID project profile no longer triggers the spurious "multiple agent profiles request auto-activation" error, and the auto-activate stack fallback is no longer skipped in that state.
+- Extension macro/slot names may no longer contain `.` — forge-v1 uses dots as path separators, so dotted names were registerable but unreachable (0.5.x review A2). Regression test pins the rejection.
+- Static prompt analysis now reports macro dependency cycles as `recursion` diagnostics instead of silently stopping traversal (0.5.x review A5). Regression test pins a single deduplicated diagnostic per cycle.
+- Dev/test Pi SDK pins aligned across both repositories at `0.84.2` (0.5.x review A4); the optional package no longer mixes `0.83.0`/`0.84.2` instances in its tree.
+
+- Web editor polish (code-review follow-up): the theme toggle moved from the legacy stacks topbar into the shared surface navigation, so it stays visible and functional on the Agent profiles surface; theme state now lives in a shared `theme.ts` module consumed by both the Vue shell and the legacy bridge. Policy editor rows no longer repeat the column labels on wide layouts (labels return when the grid stacks on narrow screens). Item/main action buttons no longer wrap their own text mid-label, and the item toolbar wraps whole buttons instead of clipping.
 
 ## [0.4.1] - 2026-08-17
 

package/README.md

@@ -14,10 +14,10 @@ Think of it as a character sheet and workbench for your AI agent.
 - Switch between coding, reviewing, writing, roleplay, and translation modes with one command.
 - Save and apply complete model/thinking/stack profiles.
 - Enforce per-stack tool policy and filter model-visible skills.
-- Use static, turn, and session variables with nested template macros.
+- Use immutable stack `parameters` with the deterministic forge-v1 template engine.
 - Apply deterministic regex transforms to outgoing prompts or finalized assistant messages.
-- Import SillyTavern presets and inspect the migration report.
 - Edit stacks and profiles in a local browser UI and inspect the exact provider payload.
+- Inspect prompt changes in the Preview dock: **Preview** compiles the live draft, **Draft diff** compares unsaved edits with disk, and **Run diff** compares recent provider turns. Git-style unified/split views include old/new line numbers, inline highlights, and changes-only/three-line/all-line context. Run metadata keeps chars/4 estimates separate from Pi's provider-reported prompt/cache usage and real cache-hit rate.
 - Run an explicitly enabled profile as an experimental, approval-gated foreground subagent.
 
 ## Install
@@ -58,7 +58,7 @@ Restart Pi or run:
 /preset ui
 ```
 
-The local editor can create, fork, validate, preview, import, export, and delete prompt stacks. Its **Agent profiles** view manages one-shot model/thinking/stack presets and experimental delegation settings. Writes require a trusted project.
+The local editor can create, fork, validate, preview, import, export, and delete prompt stacks. Its **Agent profiles** view manages one-shot model/thinking/stack presets. Writes require a trusted project. When `@zihanw/pi-forge-subagents` is installed, its schema-driven editor appears on the separate top-level **Settings** surface and persists to the optional package's `subagents.json` files.
 
 ### 3. Save a profile
 
@@ -78,9 +78,9 @@ A prompt stack is an ordered JSON document containing:
 | Item | Purpose |
 |---|---|
 | **Block** | Static `system`, `user`, `assistant`, or hidden `custom` text |
-| **Slot** | Runtime content such as tools, skills, project context, variables, date/cwd, or chat history |
+| **Slot** | Runtime content such as tools, skills, project context, date/cwd, or chat history |
 
-Stacks can `replace`, `append`, or `prepend` Pi's base system prompt. During compilation, pi-forge expands macros, inserts conversation content, enforces tool policy, filters its skill listing, and applies enabled regex rules.
+Stacks can `replace`, `append`, or `prepend` Pi's base system prompt. During compilation, pi-forge compiles forge-v1 templates over `runtime.*` / `parameters.*` / `extensions.*`, inserts conversation content, enforces tool policy, filters its skill listing, and applies enabled regex rules.
 
 Agent profiles are project-local references to an exact provider/model, thinking level, and prompt stack. They intentionally do not duplicate tool or skill policy—the referenced stack remains the source of truth.
 
@@ -88,7 +88,6 @@ Start with these examples:
 
 - [Default Pi mirror](examples/default-prompt-stack.json) keeps normal Pi behavior while making its sections movable.
 - [Focused reviewer](examples/reviewer-prompt-stack.json) creates a read-only review layout with an explicit latest-user target.
-- [SillyTavern DM writer](examples/sillytavern-dm-writer-prompt-stack.json) demonstrates characters, variables, history placement, and regex cleanup.
 - [Custom system-status extension](examples/custom-system-status-extension/README.md) registers a trusted macro and slot.
 
 ## Common commands
@@ -111,9 +110,9 @@ See the [complete command reference](docs/reference/commands.md).
 
 ## Experimental foreground delegation
 
-pi-forge can run an explicitly enabled profile as a clean, foreground Pi subprocess. The model can discover eligible profiles with `forge_subagent_profiles` and invoke one with `forge_subagent`; humans use `/forge-agent plan` and `/forge-agent run`.
+The optional `@zihanw/pi-forge-subagents` package provides foreground delegation on top of pi-forge's `/subagent` host port. The model can discover eligible profiles with `forge_subagent_profiles` and invoke one with `forge_subagent`; humans use `/forge-agent plan` and `/forge-agent run`.
 
-This feature is **experimental** and profiles are not delegatable by default. Enable each profile in the trusted project's `.pi/forge/config.json` or its web-editor delegation card. Interactive execution presents an immutable plan for approval unless the project explicitly authorizes unattended model invocation.
+This feature is **experimental** and profiles are not delegatable by default. Enable each profile in the trusted project's `.pi/forge/subagents.json` (or the optional package's read-only legacy fallback in `.pi/forge/config.json.subagents`). Interactive execution presents an immutable plan for approval unless the project explicitly authorizes unattended model invocation.
 
 > **Security boundary:** The current backends are shared-user processes, not operating-system sandboxes. “Read-only” describes the model-visible tool policy. The child retains the invoking user's OS read permissions, and readable content may be sent to the selected provider and retained in Pi's session data. Timeout and cancellation are best effort, and `/tree` cannot undo provider requests, billing, or external effects.
 
@@ -124,11 +123,11 @@ Read [foreground delegation and its safety model](docs/guides/delegation.md) bef
 ### Learn
 
 - [Getting started](docs/getting-started.md)
+- [Migrating to 0.5](docs/guides/migrating-to-0.5.md)
 - [Prompt-stack concepts](docs/concepts/prompt-stacks.md)
 - [Agent-profile concepts](docs/concepts/agent-profiles.md)
 - [Web editor](docs/guides/web-editor.md)
 - [Prompt-stack patterns and examples](docs/guides/use-cases.md)
-- [SillyTavern import](docs/guides/sillytavern-import.md)
 - [Custom macros and slots](docs/guides/custom-macros-and-slots.md)
 - [Prompt and payload debugging](docs/guides/debugging.md)
 
@@ -139,14 +138,16 @@ Read [foreground delegation and its safety model](docs/guides/delegation.md) bef
 - [Macros and slots](docs/reference/macros-and-slots.md)
 - [Configuration](docs/reference/configuration.md)
 - [Public API policy](docs/reference/public-api.md)
-- [Experimental subagent adapter](docs/reference/subagent-adapter.md)
+- [Experimental subagent host port](docs/reference/subagent-host-port.md)
 
 ### Develop and design
 
 - [Development setup](docs/development/setup.md)
+- [Architecture and development rules](docs/development/architecture-rules.md)
+- [0.5 architecture plan](docs/design/architecture-0.5.md)
 - [Release process](docs/development/release.md)
 - [Roadmap](docs/development/roadmap.md)
-- [Historical design archive](docs/design/README.md)
+- [Architecture and design index](docs/design/README.md)
 
 Chinese user documentation starts at [docs/zh-CN/README.md](docs/zh-CN/README.md).
 

package/README.zh-CN.md

@@ -16,7 +16,6 @@
 - 按栈严格限制工具，并过滤模型可见的 skills。
 - 使用静态、轮次和会话变量，以及支持嵌套的模板宏。
 - 对发给模型的 prompt 或最终 assistant 消息执行确定性 regex 转换。
-- 导入 SillyTavern 预设并检查迁移报告。
 - 在本地 Web 编辑器中管理 stack/profile，并检查实际 provider payload。
 - 用明确启用的 profile 运行实验性、需要审批的前台 subagent。
 
@@ -58,7 +57,7 @@ cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
 /preset ui
 ```
 
-本地编辑器可以新建、fork、校验、预览、导入、导出和删除 prompt stack，并可在新建/fork/导入时明确选择写入项目或用户全局存储。切换到 **Agent profiles** 可以浏览项目与全局 profile、编辑和删除全局 profile（通过显式 `global:<id>` 路由），并管理实验性 delegation 配置。写入操作要求项目已被信任。
+本地编辑器可以新建、fork、校验、预览、导入、导出和删除 prompt stack，并可在新建/fork/导入时明确选择写入项目或用户全局存储。Preview dock 提供带旧/新行号和行内高亮的 unified/split diff，可只看变化行或保留三行/全部上下文；Run diff 会把 chars/4 估算与 Pi 返回的真实 prompt/cache usage、cache hit rate 明确分开。切换到 **Agent profiles** 可以浏览项目与全局 profile、编辑和删除全局 profile（通过显式 `global:<id>` 路由）。写入操作要求项目已被信任。Delegation 配置由可选包 `@zihanw/pi-forge-subagents` 的 `subagents.json` 文件管理，不在编辑器中。
 
 ### 3. 保存 profile
 
@@ -88,7 +87,6 @@ Agent profile 是项目级或用户全局预设，引用精确 provider/model、
 
 - [默认 Pi mirror](examples/default-prompt-stack.json)：保留 Pi 默认行为，同时让所有区域都可移动。
 - [专注代码审查](examples/reviewer-prompt-stack.json)：只读工具策略、背景历史和明确的最新用户目标。
-- [SillyTavern DM writer](examples/sillytavern-dm-writer-prompt-stack.json)：角色、变量、历史布局和 regex 清理。
 - [自定义 system-status extension](examples/custom-system-status-extension/README.md)：注册可信 macro 和 slot。
 
 ## 常用命令
@@ -111,9 +109,9 @@ Agent profile 是项目级或用户全局预设，引用精确 provider/model、
 
 ## 实验性前台 delegation
 
-pi-forge 可以把明确授权的 profile 作为干净、前台运行的 Pi 子进程。模型通过 `forge_subagent_profiles` 发现可用 profile，再用 `forge_subagent` 调用；用户可以使用 `/forge-agent plan` 和 `/forge-agent run`。
+可选包 `@zihanw/pi-forge-subagents` 在 pi-forge 的 `/subagent` host port 之上提供前台 delegation。模型通过 `forge_subagent_profiles` 发现可用 profile，再用 `forge_subagent` 调用；用户可以使用 `/forge-agent plan` 和 `/forge-agent run`。
 
-此功能仍是**实验性功能**，profile 默认不能委派。请在可信项目的 `.pi/forge/config.json`（授权 `project:<id>`）或用户全局 `~/.pi/forge/config.json`（授权 `global:<id>`）中逐个启用，也可以使用 Web 编辑器 delegation 卡片。除非项目明确授权无人值守的模型调用，否则执行前会显示与不可变计划绑定的审批界面。
+此功能仍是**实验性功能**，profile 默认不能委派。请在可信项目的 `.pi/forge/subagents.json`（或可选包只读兼容的 `.pi/forge/config.json.subagents`）中逐个启用。除非项目明确授权无人值守的模型调用，否则执行前会显示与不可变计划绑定的审批界面。
 
 > **安全边界：** 当前 backend 是 shared-user 进程，不是操作系统沙箱。“只读”只描述模型可见工具策略。Child 仍有启动用户的 OS 读取权限；可读内容可能发送给所选 provider，并保留在 Pi session 数据中。Timeout 和取消仅为 best effort，`/tree` 不能撤销 provider 请求、计费或外部影响。
 

package/SUBAGENT_ADAPTER_CONTRACT.md

@@ -1,5 +1,7 @@
 # Subagent adapter contract
 
-The authoritative experimental contract moved to [`docs/reference/subagent-adapter.md`](docs/reference/subagent-adapter.md).
+The authoritative experimental contract moved to [`docs/reference/subagent-host-port.md`](docs/reference/subagent-host-port.md).
+
+The 0.4 execution contract (request, preflight, plan, response, validators) moved to the optional `@zihanw/pi-forge-subagents` package in 0.5.0; the main package keeps only the versioned host port.
 
 This compatibility pointer remains at the published root path so existing links continue to work.

package/dist/agent-profile.d.ts

@@ -2,39 +2,24 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type Model } from "@earendil-works/pi-ai";
 import { type ResourceScope } from "./resource-identity.ts";
 import type { LoadedPromptStack } from "./types.ts";
-export declare const AGENT_PROFILE_TYPE: "pi-forge.agent-profile";
-export declare const AGENT_PROFILE_THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-export interface AgentProfileModelReference {
-    provider: string;
-    id: string;
-}
-export interface AgentProfile {
-    schemaVersion: 1;
-    type: typeof AGENT_PROFILE_TYPE;
-    id: string;
-    name?: string;
-    description?: string;
-    autoActivate?: boolean;
-    model: AgentProfileModelReference;
-    thinkingLevel: ThinkingLevel;
-    promptStack: string | null;
-}
-export type AgentProfileDiagnosticLevel = "error" | "warning" | "info";
-export interface AgentProfileDiagnostic {
-    level: AgentProfileDiagnosticLevel;
-    message: string;
-    field?: string;
-}
-export interface LoadedAgentProfile {
-    profile: AgentProfile;
-    filePath: string;
-    scope: "global" | "project";
-    key: {
-        scope: "global" | "project";
-        id: string;
-    };
-    diagnostics: AgentProfileDiagnostic[];
-}
+import { type AgentProfile, type AgentProfileDiagnostic, type AgentProfileModelReference, type LoadedAgentProfile } from "./codecs/agent-profile.ts";
+export { AGENT_PROFILE_TYPE, AGENT_PROFILE_THINKING_LEVELS, validateAgentProfile, validateAgentProfilePromptStackScope } from "./codecs/agent-profile.ts";
+export type { AgentProfile, AgentProfileDiagnostic, AgentProfileDiagnosticLevel, AgentProfileModelReference, LoadedAgentProfile } from "./codecs/agent-profile.ts";
+export declare function loadAgentProfileFile(filePath: string, scope?: "global" | "project"): LoadedAgentProfile;
+export { agentProfilePath, agentProfilesDir } from "./storage.ts";
+export declare function isValidAgentProfileId(id: string): boolean;
+export declare function loadAgentProfiles(cwd: string): LoadedAgentProfile[];
+export declare function loadAgentProfilesScoped(cwd: string, globalDir?: string): LoadedAgentProfile[];
+export declare function loadGlobalAgentProfiles(globalDir?: string): LoadedAgentProfile[];
+export declare function chooseAutoActivateAgentProfile(profiles: readonly LoadedAgentProfile[]): LoadedAgentProfile | undefined;
+export declare function hasAutoActivateAgentProfile(profiles: readonly LoadedAgentProfile[]): boolean;
+export declare function resolveAgentProfile(loaded: LoadedAgentProfile, resources: AgentProfileResolutionResources): ResolvedAgentProfile;
+export declare function isUsableAgentProfile(loaded: LoadedAgentProfile): boolean;
+export declare function isResolvedAgentProfileUsable(resolved: ResolvedAgentProfile): boolean;
+export declare function hasAgentProfileErrors(diagnostics: readonly AgentProfileDiagnostic[]): boolean;
+export declare function renderAgentProfileDiagnostics(diagnostics: readonly AgentProfileDiagnostic[]): string;
+export declare function agentProfileFingerprint(profile: AgentProfile): string;
+export declare function isAgentProfileProvenance(value: unknown): value is AgentProfileProvenance;
 export interface AgentProfileResolutionResources {
     models: readonly Model<any>[];
     availableModels?: readonly Model<any>[];
@@ -62,33 +47,4 @@ export interface AgentProfileProvenance {
     appliedAt: string;
     snapshot: AgentProfileRuntimeSnapshot;
 }
-export { agentProfilePath, agentProfilesDir } from "./storage.ts";
-export declare function isValidAgentProfileId(id: string): boolean;
-export declare function loadAgentProfiles(cwd: string): LoadedAgentProfile[];
-/**
- * Load both global and project profiles. Global definitions are user-owned
- * and always load; project definitions load from the trusted project dirs.
- * The caller decides whether project trust applies before calling.
- */
-export declare function loadAgentProfilesScoped(cwd: string, globalDir?: string): LoadedAgentProfile[];
-/** Load only the user-owned global profiles, used by untrusted projects. */
-export declare function loadGlobalAgentProfiles(globalDir?: string): LoadedAgentProfile[];
-export declare function chooseAutoActivateAgentProfile(profiles: readonly LoadedAgentProfile[]): LoadedAgentProfile | undefined;
-export declare function hasAutoActivateAgentProfile(profiles: readonly LoadedAgentProfile[]): boolean;
-export declare function loadAgentProfileFile(filePath: string, scope?: "global" | "project"): LoadedAgentProfile;
-export declare function validateAgentProfile(profile: AgentProfile): AgentProfileDiagnostic[];
-/**
- * Validate the profile's stored `promptStack` selector against the profile's
- * own scope. Bare references stay scope-relative; only global profiles are
- * prohibited from referencing project stacks explicitly. Used by write paths
- * so edited JSON cannot persist a scope-unsafe dependency.
- */
-export declare function validateAgentProfilePromptStackScope(profile: AgentProfile, scope: ResourceScope): AgentProfileDiagnostic[];
-export declare function resolveAgentProfile(loaded: LoadedAgentProfile, resources: AgentProfileResolutionResources): ResolvedAgentProfile;
-export declare function isUsableAgentProfile(loaded: LoadedAgentProfile): boolean;
-export declare function isResolvedAgentProfileUsable(resolved: ResolvedAgentProfile): boolean;
-export declare function hasAgentProfileErrors(diagnostics: readonly AgentProfileDiagnostic[]): boolean;
-export declare function renderAgentProfileDiagnostics(diagnostics: readonly AgentProfileDiagnostic[]): string;
-export declare function agentProfileFingerprint(profile: AgentProfile): string;
-export declare function isAgentProfileProvenance(value: unknown): value is AgentProfileProvenance;
 //# sourceMappingURL=agent-profile.d.ts.map

package/dist/agent-profile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-profile.d.ts","sourceRoot":"","sources":["../src/agent-profile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-profile.d.ts","sourceRoot":"","sources":["../src/agent-profile.ts"],"names":[],"mappings":"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"}