From 242911331abe8fd12e12ba745801ecb316b444c8 Mon Sep 17 00:00:00 2001 From: Federico Jaramillo Martinez Date: Wed, 22 Jul 2026 09:36:32 +0200 Subject: [PATCH] docs: document global provider policy and extension registration rejection --- .changeset/global-provider-policy.md | 5 +++++ docs/plugins.html | 7 +++++++ docs/plugins.md | 6 ++++++ 3 files changed, 18 insertions(+) create mode 100644 .changeset/global-provider-policy.md diff --git a/.changeset/global-provider-policy.md b/.changeset/global-provider-policy.md new file mode 100644 index 0000000..0910f51 --- /dev/null +++ b/.changeset/global-provider-policy.md @@ -0,0 +1,5 @@ +--- +"@jmfederico/pi-web": patch +--- + +Support only globally configured providers (Pi built-ins, environment credentials, and the agent directory's `models.json`). Provider registrations from Pi extensions (`pi.registerProvider`) are now ignored and reported with a session warning instead of leaking into every concurrent session; all other extension features keep working. Configure such providers globally in the agent directory's `models.json` to use them. Session daemon code changed: after updating, restart `pi-web-sessiond.service` manually (`systemctl --user restart pi-web-sessiond`). diff --git a/docs/plugins.html b/docs/plugins.html index bb3a304..c2fa8c8 100644 --- a/docs/plugins.html +++ b/docs/plugins.html @@ -162,6 +162,13 @@ prompt files as supported by Pi. Reload the browser page separately for newly discovered or changed PI WEB browser plugins. A routine session daemon restart is not required.

+

+ One exception applies to Pi package extensions: PI WEB supports only globally configured providers + (Pi built-ins, environment credentials, and the agent directory's models.json). If an + extension calls pi.registerProvider, PI WEB ignores the registration and warns in the + session; everything else the extension registers keeps working. Configure such providers globally in + the agent directory's models.json instead. +

diff --git a/docs/plugins.md b/docs/plugins.md index cbcfcd2..fb1d57c 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -25,6 +25,12 @@ When machine federation is enabled, **Settings → Pi packages** targets the cur Use **Settings → PI WEB plugins** to enable or disable discovered PI WEB browser plugins before the browser imports them. In a federated setup, this plugin enablement surface targets the currently selected machine and labels where changes are saved. If an older or unavailable remote PI WEB server does not advertise selected-machine settings support, PI WEB reports the plugin settings as unsupported or unavailable instead of silently falling back to the gateway. After installing, removing, or updating a Pi package, type `/reload` in each idle PI WEB session on the target machine to refresh Pi runtime resources such as extensions, skills, prompt templates, themes, and context/system prompt files as supported by Pi. Reload the browser page separately for newly discovered or changed PI WEB browser plugins. A routine session daemon restart is not required. +## Extension provider registrations + +PI WEB only supports globally configured providers: Pi built-ins, environment credentials, and providers declared in the agent directory's `models.json` (the directory selected by `agent.dir`; see [Configuration](https://pi-web.dev/config)). All sessions share one daemon-wide provider set, so extensions cannot add their own: if a Pi extension calls `pi.registerProvider(...)`, PI WEB ignores the registration and shows a warning in the session naming the provider. The extension itself still loads and everything else it registers keeps working; only the ignored provider's models never appear, so an extension that requires its own provider may load but remain unusable. + +To use such a provider, configure it globally in the agent directory's `models.json` instead. Project-level `models.json` files do not add providers to PI WEB sessions. + ## Trust model Plugins run as JavaScript in the browser app. Treat them as trusted code: