[jasper-yl]

Which issue or RFC does this PR close?

Implements RFC #2579 (plugin hot reload, data upgrades, plugin route descriptions and MCP tools). Builds on #2616: this branch contains its commits, so review the commits after d4b0f1b0 and merge after #2616.

Rationale for this change

#2616 loads plugins only at Server startup, so updating a plugin needs a restart, and plugins have no hook to adapt their data to a new version. RFC #2579 lets a running Server follow the plugin directory, runs each version's upgrade before it is used, and makes plugin routes discoverable through OpenAPI and MCP.

What changes are included in this PR?

• Reloading. Each Server process rescans the plugin directory every POWERCONTEXT_SERVER_PLUGINS_RESCAN_SECONDS (default 60, 0 off). A directory whose content digest is the same in two consecutive scans and differs from the version in use is copied to a read-only snapshot under the data directory, checked there, and added, updated, or removed without a restart. Plugin code is imported only from snapshots.
• Switching versions. A new version's host processes take requests once ready; the old version's processes finish what they hold and stop. Workers launch from the version current at dispatch, so running Workers finish on their snapshot; the Supervisor binding is replaced only when scheduling fields change. Removed plugins unregister their family, merges, Source binding, routes, pages, and tools; Source Definition manifests stay registered.
• Upgrade. ArtifactPlugin(upgrade=..., upgrade_timeout_seconds=600): called every time a version loads, before setup, as the plugin itself (reads and writer without a caller, at most one write transaction). Instances without host processes (the background role) run it in a short-lived child before using the new version. A failed check or upgrade keeps the previous version and is reported in last_check_failure.
• Route descriptions and MCP. GET /v1/plugins/{name}/openapi.json describes a plugin's routes. Routes declared with mcp=True are MCP tools named <plugin>__<handler>, listed from the plugins loaded at each tools/list and called through the route itself.
• Listing. /v1/plugins adds version_digest, declaration_digest, activated_at, last_check_failure, routes, and pages.
• Observability. plugin.changed events with plugin_name, plugin_event, version_digest, declaration_digest; plugin.scanned with scan_ms.
• Docs (en and zh): plugin guide sections on updating plugins, upgrade, MCP and OpenAPI; configuration and observability references.

Are there any user-facing changes?

Yes. Plugin directory changes take effect without a restart; set POWERCONTEXT_SERVER_PLUGINS_RESCAN_SECONDS=0 to keep startup-only loading. New API GET /v1/plugins/{name}/openapi.json and new fields on /v1/plugins; the Desktop contract is regenerated and qualified. No persisted format changes; release/upgrade-support.json records the review of the in-process authorization profile change.

How was this change tested?

• Full suite on a Linux VM (Ubuntu 24.04, 4 cores) before the rebase onto d4b0f1b0 (same code, earlier hashes): uv run pytest -n 4 — 10373 passed, 995 skipped, 36 failed. 32 failures were Kimi Code, ZCode, and installation tests that need Node, which the VM lacked; with Node installed they pass (74 passed). The other 4 were the upgrade release gate, fixed in this PR (tests/test_upgrade_release_gate.py: 132 passed).
• make docs-test on the VM: verified 1109 public pages and their internal links.
• Hooks (uv run prek run) and uv run ty check pass locally.
• Desktop qualification sqlite-plugin-reload-5e365242-v1: anonymous loopback, static Bearer, HTTPS with CA/base path, and enforced Provider modes passed against the wheel built from 5e365242; bundled_product_qualification_covers_every_desktop_operation passed.
• tests/e2e/test_plugin_reload.py runs a real Server with a 0.5 s rescan: a version change takes effect without restart and its upgrade runs first; a version whose upgrade fails is not used and the previous version keeps serving; openapi.json; MCP lists and calls the plugin tool; an added plugin loads and a removed one disappears with its routes and tools.
• The DSH, Cindy, and OpenCode bundles are rebuilt from the regenerated operation tables (make js-test, make opencode-test, and make cindy-test compare them).
• The background-role upgrade child was checked directly: a succeeding upgrade lets the version be used, a raising one does not.

AI usage statement

Implemented with Claude Code (Claude Opus 5.5) under the author's direction; the author made the design decisions in the RFC review. Claude Code ran the tests and checks listed above.

🤖 Generated with Claude Code

[hidb4ai]

Reviewed e11070394247e80e1e19e0bcea4536ad6cd7399a, focusing on the changes after the #2616 head (d4b0f1b0). Requesting changes for four reproduced failures in snapshot retention, failed-update recovery, upgrade timeouts, and plugin OpenAPI references. Details are inline.

[hidb4ai]

[P1] Preserve snapshots still used by another Server process

keep contains only the starting process's current snapshots, but this directory is shared across Server processes. I reproduced this with two real Servers sharing POWERCONTEXT_HOME: A loaded v1 with rescanning disabled; after deploying v2, starting B deleted A's v1 snapshot. A's previously successful handler reading a file under ctx.plugin_dir then returned HTTP 500, while B served v2 successfully. The same exposure applies to an old host or Worker still draining during a rolling update. Snapshot age and this process's current version do not establish that no other process is using it; retain snapshots across process lifetimes before deleting them. The scan-time collector also needs this guarantee because _activate() adds reused snapshots to _created.

[hidb4ai]

[P2] Keep the old plugin when the new declaration cannot register

A declaration can pass the child-process check and still fail _register(), for example when it changes a Source Definition schema without changing that definition's name/version. On a real Server, changing the ticket input's min_length from 1 to 2 produced StoredPayloadConflictError; this branch then unloaded the working plugin, cleared its version/family/routes, and made its OpenAPI endpoint return 404. Rejecting the conflicting definition is correct, but the promised failed-update behavior is to keep the old version serving and record last_check_failure. Complete the fallible registration checks before switching, or restore the previous manifest, registrations, binding, and host on failure.

[hidb4ai]

[P2] Apply the upgrade deadline to the host watchdog too

Increasing wait_ready()'s timeout does not extend PluginHost._watch(): it still terminates every not-ready host after READY_TIMEOUT_SECONDS (60 seconds), and the host sends HostReady only after upgrade() and setup(). I reproduced a reload with upgrade_timeout_seconds=90 and an upgrade that sleeps for 65 seconds: the host was killed with start_timeout at 60 seconds, the plugin reported last_check_failure="start_failed", and v1 kept serving. Thus valid upgrades longer than 60 seconds cannot activate even with the documented 600-second default. Make the watchdog honor the declared upgrade allowance as well.

[hidb4ai]

[P2] Rebase nested model references in the plugin OpenAPI document

Pydantic schemas containing nested models use references such as #/$defs/Child. Embedding that schema here leaves the references relative to the OpenAPI document root, while $defs remains inside the individual request/response schema. I reproduced a plugin with Envelope(child: Child): its POST route returned 200, but the returned openapi.json contained two unresolved #/$defs/Child references, one for the request and one for the response. Consumers cannot resolve these otherwise valid models. Relocate definitions and rewrite references, or otherwise give each embedded schema a valid reference base; the response-schema insertion above needs the same treatment.