@zihanw/pi-forge 0.4.0-beta.1 → 0.4.1

package/CHANGELOG.md

@@ -8,6 +8,49 @@ In 0.x development, breaking changes may occur in minor releases and will be exp
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-08-17
+
+### Added
+
+- **Scoped global agent profiles and prompt stacks.** Profiles and stacks can now live in the user-owned global forge directory or the trusted project, with project resources shadowing same-ID global resources for bare selectors. Qualified `global:<id>` and `project:<id>` selectors provide exact addressing across commands, saved session state, profile stack references, delegation policy, subagent plans, and the browser editor. Global profiles resolve only global stacks, while project profiles may explicitly reuse global stacks; untrusted projects remain browse-only and cannot auto-activate or delegate resources. The browser editor shows scope and shadow badges, edits/deletes global resources only through explicit `global:<id>` routes, and provides project-default scope selectors for creating profiles and creating, forking, or importing prompt stacks. The zh-CN documentation now covers the scoped model.
+- **Parallel foreground subagent invocation.** `forge_subagent` now registers as a parallel-execution tool, so the parent model can issue several calls in one turn and they prepare, approve, and execute concurrently. Pi's single-slot select/editor UI cannot host two dialogs at once, so interactive approval dialogs (including View full prompt) are serialized through a shared gate inside `requestForgeSubagentApproval` — the same gate covers `/forge-agent run` — while approved runs still overlap; unattended trusted-project invocation never enters the gate and is fully concurrent. Each run remains an independent subprocess and provider request, so a burst of parallel calls multiplies provider cost and process load.
+- **Embedded subagent profile summary in the tool description.** `subagents.summaryInToolDescription` (default `false`, settable in global or trusted-project config) embeds a compact summary of enabled subagent profiles directly in the `forge_subagent` tool description—id, name, model/thinking level, stack, backend, and timeout—so the parent model can pick a frequently used profile without a `forge_subagent_profiles` discovery call. Unavailable enabled profiles stay visible with their first error so the model does not attempt them, ready profiles sort first, and the block is capped at 8 profiles and 1,000 characters. The description re-registers only when the rendered summary changes (profiles, stacks, or configuration), so per-turn lifecycle refreshes are no-ops, and disabling the option reverts the description to the base form. `forge_subagent_profiles` remains the authoritative full-detail surface.
+
+## [0.4.0] - 2026-08-02
+
+### Added
+
+- **Per-profile subagent delegation in the browser editor.** Each profile now has a delegation card that reports its effective delegation state, backend, timeout, and sources, and trusted projects can toggle the `subagents.profiles.<id>` opt-in with backend and timeout overrides without hand-editing `.pi/forge/config.json`. The editor writes the project config while preserving unrelated keys and removing emptied entries, warns when the effective backend is not registered, marks delegation-enabled profiles with a `subagent` badge, and keeps project defaults and `allowAgentInvocationWithoutApproval` read-only. Backend listing degrades to registered IDs when backend construction is unavailable, so profile browsing never depends on backend runtime resources.
+- **Agent-profile editor foundation.** The localhost editor now has top-level navigation between prompt stacks and project agent profiles. The profile surface lists exact model/thinking/stack targets, auto-activation and last-applied markers, current-to-target transitions, effective tools, shared resolution diagnostics, applicability, provenance, and runtime drift. Trusted projects can create, validate, edit, apply once, and delete project-local profiles through a token-protected API backed by the existing resolver, transactional application service, and guarded repository.
+- **Configurable subagent backend selection.** The execution backend is now layered configuration rather than a fixed default: `subagents.backend` in the user-owned `~/.pi/forge/config.json` sets the global default, a trusted project's `.pi/forge/config.json` overrides it, trusted-project per-profile policy can refine it, and `/forge-agent plan|run <profile> --backend <id>` or the interactive `forge_subagent` `backend` parameter overrides a single run. The experimental `pi-rpc-readonly` backend registered in the previous prerelease is now reachable from the product. There is deliberately no fallback to another backend when the selected one is unavailable; unattended `forge_subagent` invocation is pinned to the effective configured profile backend and rejects per-call backend overrides. `forge_subagent_profiles` and `/forge-agent backends` report resolved values and sources.
+- **Explicit per-profile delegation policy.** Agent profiles are no longer automatically exposed as subagents. Trusted-project `subagents.profiles.<id>` entries explicitly enable delegation and can override backend and timeout per profile while keeping runner policy out of portable agent-profile JSON. Disabled and unlisted profiles remain available to ordinary `/profile` workflows but are hidden from model discovery and rejected before preparation by command, tool, and runtime paths. Global profile entries warn and are ignored because profiles and prompt stacks are project-local; interactive backend overrides remain highest priority.
+- **Conversation fingerprint visibility.** `AgentExecutionPlan` now carries the runtime-issued `conversationFingerprint` alongside the execution fingerprint. `/forge-agent plan`, the approval summary, the full-prompt viewer, and the `forge_subagent` plan details display it, so cross-backend prompt fidelity is observable (equal conversation fingerprints with backend-distinct execution fingerprints).
+
+### Changed
+
+- **Declarative stack item editor.** Prompt blocks, runtime slots, and structured slot options now render through a lifecycle-managed Vue component. Form and raw-JSON modes share one reactive draft, preserve unknown option keys, and keep malformed JSON visible while preventing validation, preview, or save.
+- **First declarative web-editor tabs.** The policy and regex editors now run as lifecycle-managed Vue components while the remaining stack editor stays on the compatibility bridge. Their drafts remain plain JSON at the bridge boundary, validation errors survive tab changes, repeated mounts clean up safely, and advanced rule/policy fields are preserved while editing.
+- **Declarative stack settings editor.** Context options, stack variables, and the raw JSON recovery view now share the same lifecycle-managed Vue tab host. Duplicate-variable errors remain authoritative across tab changes, raw JSON stays unapplied until explicitly accepted, and applying a replacement stack resets the other tab drafts through one plain-JSON boundary.
+- **Declarative stack metadata.** Stack identity, name, mode, auto-activation, description, file provenance, collapse state, and dirty-state signaling now render through a lifecycle-managed Vue component while preserving the established browser controls and immutable-ID behavior.
+- **Viewport-safe subagent approval.** The interactive approval selector now shows a bounded one-line task preview and compact execution metadata instead of embedding the full multi-line review in an unbounded selector title. `View full prompt` opens the complete approval details, full fingerprints, and exact provider-bound prompt in Pi's internally scrollable editor, avoiding terminal-scrollback jumps in small terminals such as VS Code's integrated terminal.
+- **Configurable foreground subagent timeout.** `subagents.timeoutMs` configures the best-effort default from 1,000 through 3,600,000 milliseconds with a 60,000-millisecond built-in value, while `subagents.profiles.<id>.timeoutMs` can override it per enabled profile. Malformed values preserve the preceding valid/default value with a warning, and discovery, backend, plan, and approval surfaces show the effective timeout.
+- **Published subagent runtime integration.** Pinned `@zihanw/pi-subagent-runtime@0.1.0-beta.2` instead of a sibling `file:` dependency. Host compilation now consumes the runtime's validated accepted preflight directly, and preparation forwards its `AbortSignal` through the public runtime API, removing the temporary `hostCompilePreflight()` and `prepareWithAbort()` shims. Runtime beta.2 consumes Pi SDK packages as host-provided peers and resolves model registries structurally, avoiding a private-class identity dependency on one Pi release.
+- **Runtime-issued plan fingerprints.** `createAgentExecutionPlan()` now requires the runtime-issued conversation and execution fingerprints as inputs instead of computing a host-side execution fingerprint. `validateAgentExecutionPlan()` validates fingerprint shape and internal consistency; substituted-plan detection is the runtime's sealed-plan binding, not host recomputation.
+- **Portable validators unified with the runtime core.** The subagent contract's access, limit, prompt-runtime, backend-descriptor, and access-enforcement validators are re-exported from `@zihanw/pi-subagent-runtime` (adapted to the host collecting style), removing the duplicated portable implementations. Host-specific artifacts (selected context, context budget, media, usage, artifacts, traces, and the richer host access-receipt cross-checks) keep their local validators.
+- **Host-provided Pi compatibility.** Pi SDK packages and `typebox` are wildcard optional peers instead of private runtime dependencies, while exact versions remain development-only for reproducible builds. The full verification surface passes against Pi 0.82.1 and 0.83.0, and scheduled CI checks the latest published Pi family so incompatibilities are found without constraining every host update.
+
+### Removed
+
+- **Breaking: legacy subagent compatibility surfaces.** Removed the `src/subagent-contract.ts` compatibility barrel (import the identical surface from `@zihanw/pi-forge/subagent` or the package root), the `subagentExecutionFingerprint` host fingerprint helper (execution fingerprints are runtime-issued), and the `scripts/subagent-sdk-spike*` diagnostic harness with its `spike:subagent` npm script and test. The spike's media-transport and trusted-extension preparation diagnostics are recorded as coverage debt in `docs/development/roadmap.md` and return with productized delegated media tasks.
+
+### Fixed
+
+- **Profile editor state synchronization.** Returning to agent profiles now refreshes resolution after prompt-stack changes, so deleted or changed stack references immediately fail preflight instead of showing stale applicability. Unsaved delegation drafts survive same-profile refreshes and require confirmation before profile/editor navigation, manual reload, or deletion; browser unloads also use the standard unsaved-change guard. Deleting a profile now removes its effective `subagents.profiles.<id>` delegation policy, preventing a later profile with the same ID from silently inheriting delegation authority.
+- **Restored viewport-constrained editor layout.** The Vue app shell's mount element had no height, so every `height: 100%`/`calc()` below it collapsed to content height while `body` clipped the overflow without a scroll path: the delegation card, profile sidebar rows, and the stacks workspace were silently cut off at desktop window sizes. Both surfaces now size through flex `min-height: 0` chains with internal scroll regions, the sidebar list no longer assumes a fixed header height, and the narrow-width profiles layout stacks without phantom gaps. A browser regression test asserts both surfaces stay within the viewport and that bottom-of-page controls are reachable by scrolling.
+- **Narrow-window stack editing.** The stacked single-column workspace no longer stretches the items pane into dead space, the prompt-content editor keeps a usable 220px minimum height with vertical resize instead of collapsing to two lines, item fields lay out in two columns, and the diagnostics panel is now collapsible: a slim summary header (auto-expanded when errors or warnings exist, collapsed when clean, with an explicit user toggle and `aria-expanded` state) replaces the fixed 128px region.
+- **Editor UX polish.** Profiles default-select the last-applied or first healthy profile instead of the alphabetically-first broken one; the delegation card distinguishes its saved policy from an unsaved draft and uses a bounded number input for timeout overrides; the profile editor warns inline when the typed model lacks configured authentication; surface navigation exposes `aria-current`; harness-driven tests no longer read the developer's real global pi-forge config.
+- **Single auto-activation enforced on profile save.** The browser editor's create and save APIs now reject a profile that requests auto-activation while another project profile already does (409), matching the existing validation diagnostic instead of writing an ambiguous configuration that the loader would then flag on both profiles. Browser coverage now also exercises the single auto-activation rule, registry-populated model options, and runtime drift reporting after external model, thinking-level, and stack changes.
+
 ## [0.4.0-beta.1] - 2026-07-18
 
 ### Added
@@ -50,7 +93,8 @@ In 0.x development, breaking changes may occur in minor releases and will be exp
 
 - The npm tarball no longer includes physical `src/` files and uses compiled runtime entries. Legacy `@zihanw/pi-forge/src/*` imports continue to resolve to compiled modules, while development documentation directs source modifications through a repository clone and explicit local TypeScript extension entry.
 - The extension entry point is now a small composition root; prompt-stack state, one-shot profile activation, tool-policy/preview behavior, and shared web-editor lifecycle live in focused runtime modules.
-- The web editor client is authored as strict TypeScript modules for API transport, DOM access, policy editing, regex editing, preview/payload inspection, and orchestration. A build-only esbuild step produces the self-contained script used by the localhost editor, and verification rejects stale generated output.
+- The web editor client is authored as strict TypeScript/Vue source with a dedicated browser typecheck. A build-only Vite pipeline emits self-contained JavaScript and CSS strings for the localhost editor, and verification rejects stale generated output without publishing browser-only source modules.
+- **Breaking: browser-client compatibility paths.** `@zihanw/pi-forge/src/web-editor/client/*` imports are now explicitly blocked instead of matching the broad legacy `src/*` export wildcard. Browser implementation modules are build inputs rather than runtime integration surfaces; the supported editor delivery remains the generated embedded bundle.
 - The subagent contract implementation is split into focused type, canonicalization, request, preflight, tool, context, plan, response, and diagnostic modules. Existing package-root and `src/subagent-contract.ts` exports remain compatibility barrels with an exact import-surface test.
 - Backend-assisted preparation now makes the adapter, rather than the caller, provide the complete runtime compiler inputs. The registry fingerprints and validates that runtime, invokes the host compiler exactly once, binds the resulting prompt/messages/tools to execution, routes discard through the owning backend, and rejects adapters or callers that bypass, alter, or refingerprint a substitute host result.
 - Profile commands now consume shared typed repository, application, preview, provenance, and drift-status services, establishing one behavioral core for profile UI and future subagent preparation.

package/PUBLIC_API.md

@@ -1,28 +1,5 @@
-# Public API Policy
+# Public API policy
 
-pi-forge is pre-1.0. This document separates supported integration surfaces from experimental 0.4 work and compatibility paths that should not become permanent dependencies.
+The authoritative policy moved to [`docs/reference/public-api.md`](docs/reference/public-api.md).
 
-## Stable
-
-- The package default export is the Pi extension entry point declared by `pi.extensions`.
-- Package-root macro and slot registration APIs (`registerMacro`, `registerSlot`, their registry readers, render contexts, and declarative definition types) are supported for trusted reusable extensions.
-- `ForgeExtensionApi` and related registration types are supported for trusted project-local forge extensions.
-
-Stable means changes should preserve source compatibility within the documented supported release range unless a changelog entry explicitly announces a breaking release.
-
-## Experimental
-
-- Agent-profile repository, resolution, application, preview, provenance, and drift APIs are 0.4 experimental surfaces.
-- The runner-neutral subagent contract, host-resolution helpers, optional empty-by-default backend registry, retained `PiSdkIsolatedBackend`, and default `PiSubprocessBackend` adapter are 0.4 experimental surfaces.
-- New subagent integrations should import from `@zihanw/pi-forge/subagent`. The package root continues to re-export the current subagent names through the 0.4 prereleases for compatibility.
-
-Experimental APIs are typed, tested, and documented, but may be revised before the 0.4 release as real adapter and parent-integration work exposes missing semantics. Changes should still be deliberate and recorded.
-
-## Internal compatibility paths
-
-- `@zihanw/pi-forge/src/*` subpath exports exist for compatibility with earlier source-shaped imports. They resolve to compiled `dist` modules and are not a promise that every implementation module is a permanent public API.
-- `src/subagent-contract.ts` is a compatibility barrel over the focused contract modules; it does not contain a second implementation.
-- Physical `src/` files are not included in the npm tarball. Runtime installation and legacy `@zihanw/pi-forge/src/*` aliases use compiled `dist` modules; source inspection or modification requires a repository clone.
-- `scripts/subagent-sdk-spike*.ts` are diagnostic development interfaces, not a supported runner API.
-
-Before removing the compatibility subpaths, check known consumers, announce the change, and provide supported package entry points for legitimate integrations.
+This compatibility pointer remains at the published root path so existing links continue to work.