Archived
docs: distinguish Pi extensions from PI WEB plugins
This commit is contained in:
Federico Jaramillo Martinez
+51
-6
@@ -99,6 +99,7 @@
|
||||
<a href="#path-access">External path access</a>
|
||||
<a href="#manual-uploads">Manual uploads</a>
|
||||
<a href="#agent-runtime">Agent profile and companion CLI</a>
|
||||
<a href="#pi-extension-provider-baseline">Pi extension providers</a>
|
||||
<a href="#session-tools">Session tools</a>
|
||||
<a href="#completion-tools">Completion tools</a>
|
||||
</aside>
|
||||
@@ -175,7 +176,7 @@
|
||||
<li><code>pathAccess</code>: applies on the next request; existing file views may need a browser refresh.</li>
|
||||
<li><code>uploads.defaultFolder</code>: applies to newly opened Files upload dialogs and new direct drag/drop batches after config/workspace refresh.</li>
|
||||
<li><code>plugins</code>: reload the browser tab after changing PI WEB plugin enablement.</li>
|
||||
<li>Pi package install/remove/update: not a PI WEB config key; after a mutation, type <code>/reload</code> 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 PI WEB browser plugin changes. A routine session daemon restart is not required for those ordinary resources. If a globally installed extension adds, removes, or changes a provider, manually restart <code>pi-web-sessiond.service</code>; <code>/reload</code> cannot change the startup provider baseline. See <a href="plugins#extension-provider-registrations">Extension provider registrations</a>.</li>
|
||||
<li>Pi package install/remove/update: not a PI WEB config key; after a mutation, type <code>/reload</code> in each idle PI WEB session on the target machine to refresh ordinary Pi resources such as extensions, skills, prompt templates, themes, and context/system prompt files. Reload the browser page separately for PI WEB browser plugin changes. If a global Pi extension adds, removes, or changes a provider, manually restart <code>pi-web-sessiond.service</code>; <code>/reload</code> cannot change the startup provider baseline. See <a href="#pi-extension-provider-baseline">Pi extension provider baseline</a>.</li>
|
||||
<li><code>shortcuts</code>: saved settings apply in the browser after config refresh/save.</li>
|
||||
</ul>
|
||||
</section>
|
||||
@@ -347,7 +348,7 @@
|
||||
<td><code>PI_WEB_AGENT_DIR</code> (<code>PI_CODING_AGENT_DIR</code> for Pi compatibility)</td>
|
||||
<td>Global/session daemon</td>
|
||||
<td>Not supported locally</td>
|
||||
<td>Restart session daemon on that machine; affects auth, models, settings, sessions, Pi packages, and package-backed plugins</td>
|
||||
<td>Restart session daemon on that machine; affects auth, models, settings, sessions, Pi packages, and Pi-package-backed PI WEB plugins</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Agent can spawn sessions</td>
|
||||
@@ -583,12 +584,12 @@
|
||||
secret-free active profile stays fixed for the daemon lifetime. <strong>Settings → Session daemon</strong>
|
||||
saves command and directory together as desired configuration and shows whether the profile is active,
|
||||
needs a restart, or cannot be compared. Until the daemon restarts, sessions, Pi package operations,
|
||||
package-backed plugin discovery, status/install detection, and update planning continue to use the
|
||||
daemon-owned active profile; a web/API restart recovers that same active profile instead of applying the
|
||||
newly saved values.
|
||||
Pi-package-backed PI WEB plugin discovery, status/install detection, and update planning continue to use
|
||||
the daemon-owned active profile; a web/API restart recovers that same active profile instead of applying
|
||||
the newly saved values.
|
||||
</p>
|
||||
<div class="callout warning">
|
||||
If the session daemon cannot report a valid active profile, profile-dependent package and plugin
|
||||
If the session daemon cannot report a valid active profile, profile-dependent Pi package and PI WEB plugin
|
||||
operations report unavailable instead of falling back to independently resolved config. A package-managed
|
||||
update command is shown only when PI WEB can preserve the active profile with a recognized, safe Pi
|
||||
companion CLI; otherwise the command is omitted. Remote profile editing likewise requires advertised
|
||||
@@ -597,6 +598,50 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="pi-extension-provider-baseline">
|
||||
<h2>Pi extension provider baseline</h2>
|
||||
<p>
|
||||
This policy applies to <strong>Pi runtime extensions</strong>, not PI WEB browser plugins. Pi extensions
|
||||
are runtime modules loaded by the session daemon and can call <code>pi.registerProvider(...)</code>;
|
||||
PI WEB plugins are browser-side UI modules and never run in the session daemon.
|
||||
</p>
|
||||
<p>
|
||||
PI WEB shares one model runtime across all sessions. When the session daemon starts, before any project
|
||||
resources load, it initializes global Pi extensions from the active agent profile
|
||||
(<code>agent.dir</code>), including extensions supplied by globally configured Pi packages. Provider
|
||||
registrations made by synchronous or awaited asynchronous extension factories during this bootstrap join
|
||||
the shared baseline. PI WEB captures both config-form registrations
|
||||
(<code>pi.registerProvider("id", config)</code>) and native-provider registrations
|
||||
(<code>pi.registerProvider(provider)</code>), alongside Pi built-ins, environment credentials, and
|
||||
providers from the active agent directory's <code>models.json</code>.
|
||||
</p>
|
||||
<p>
|
||||
After startup capture, every later Pi extension provider registration, native registration, and
|
||||
unregistration is a no-op, regardless of source or provider ID. This includes global extensions replayed
|
||||
while sessions load, project extensions attempting to add or replace a provider, same-ID replacement or
|
||||
unregistration, lifecycle callbacks such as <code>session_start</code>, and <code>/reload</code>. The
|
||||
captured provider stays unchanged while non-provider Pi extension features continue to load and reload
|
||||
normally.
|
||||
</p>
|
||||
<p>
|
||||
Ignored mutations are written to the session-daemon log once per operation and provider ID. The log entry
|
||||
contains no provider configuration or credentials, and PI WEB does not show a session warning or
|
||||
notification. This prevents accidental provider, configuration, or credential contamination between
|
||||
projects; it is not a security boundary because Pi extensions remain trusted daemon code.
|
||||
</p>
|
||||
<p>
|
||||
Configure providers before the daemon starts: use the active agent directory's
|
||||
<code>models.json</code>, or install the Pi extension globally in that agent profile. Project Pi extensions
|
||||
and project-level <code>models.json</code> files cannot add providers to PI WEB's shared baseline.
|
||||
</p>
|
||||
<div class="callout warning">
|
||||
<strong>Restart required:</strong> after updating PI WEB—or after installing, removing, or updating a
|
||||
global Pi extension that registers providers—manually restart <code>pi-web-sessiond.service</code>
|
||||
(<code>systemctl --user restart pi-web-sessiond</code>). Restarting only the web/API service and running
|
||||
<code>/reload</code> do not rebuild the baseline.
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="session-tools">
|
||||
<h2>Session daemon tools</h2>
|
||||
<h3><code>spawnSessions</code></h3>
|
||||
|
||||
+16
-4
@@ -43,7 +43,7 @@ Process restarts depend on the key:
|
||||
- `pathAccess`: applies on the next request; existing file views may need a browser refresh.
|
||||
- `uploads.defaultFolder`: applies to newly opened Files upload dialogs and new direct drag/drop batches after config/workspace refresh.
|
||||
- `plugins`: reload the browser tab after changing PI WEB plugin enablement.
|
||||
- Pi package install/remove/update: not a PI WEB config key; after a mutation, 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 PI WEB browser plugin changes. A routine session daemon restart is not required for those ordinary resources. If a globally installed extension adds, removes, or changes a provider, manually restart `pi-web-sessiond.service`; `/reload` cannot change the startup provider baseline. See [Extension provider registrations](https://pi-web.dev/plugins#extension-provider-registrations).
|
||||
- Pi package install/remove/update: not a PI WEB config key; after a mutation, type `/reload` in each idle PI WEB session on the target machine to refresh ordinary Pi resources such as extensions, skills, prompt templates, themes, and context/system prompt files. Reload the browser page separately for PI WEB browser plugin changes. If a global Pi extension adds, removes, or changes a provider, manually restart `pi-web-sessiond.service`; `/reload` cannot change the startup provider baseline. See [Pi extension provider baseline](#pi-extension-provider-baseline).
|
||||
- `shortcuts`: saved settings apply in the browser after config refresh/save.
|
||||
|
||||
## Global config example
|
||||
@@ -113,7 +113,7 @@ Rows with JSON key `—` are runtime-only environment variables, not config-file
|
||||
| Manual file upload default folder | `uploads.defaultFolder` | — | Global + project | **Overrides**: project value wins for workspaces in that project; otherwise global/default applies | New Upload dialogs and direct drag/drop batches after config/workspace refresh |
|
||||
| Upload/body limit | `maxUploadBytes` | `PI_WEB_MAX_UPLOAD_BYTES` | Global | Not supported locally | Restart web/API and session daemon on that machine |
|
||||
| Companion CLI command | `agent.command` | `PI_WEB_AGENT_COMMAND` | Global/session daemon | Not supported locally | Restart session daemon on that machine; affects doctor/status/update checks |
|
||||
| Agent profile state directory | `agent.dir` | `PI_WEB_AGENT_DIR` (`PI_CODING_AGENT_DIR` for Pi compatibility) | Global/session daemon | Not supported locally | Restart session daemon on that machine; affects auth, models, settings, sessions, Pi packages, and package-backed plugins |
|
||||
| Agent profile state directory | `agent.dir` | `PI_WEB_AGENT_DIR` (`PI_CODING_AGENT_DIR` for Pi compatibility) | Global/session daemon | Not supported locally | Restart session daemon on that machine; affects auth, models, settings, sessions, Pi packages, and Pi-package-backed PI WEB plugins |
|
||||
| Agent can spawn sessions | `spawnSessions` | `PI_WEB_SPAWN_SESSIONS` | Global/session daemon | Not supported locally | Restart session daemon on that machine |
|
||||
| Tracked subsessions (beta) | `subsessions` | `PI_WEB_SUBSESSIONS` | Global/session daemon | Not supported locally; also requires `spawnSessions` | Restart session daemon on that machine |
|
||||
| Plugin enablement/settings | `plugins.<id>.enabled`, `plugins.<id>.settings` | — | Global | Not core local config; plugins may read their own project files | Reload browser tab |
|
||||
@@ -202,9 +202,21 @@ An alternate command always requires an explicit state directory. The command mu
|
||||
|
||||
Environment variables take precedence over the config file. `PI_WEB_AGENT_COMMAND` selects the companion CLI, `PI_WEB_AGENT_DIR` sets the profile state directory, and `PI_WEB_AGENT_SESSION_DIR` overrides session storage separately from `agent.dir`. The legacy `PI_CODING_AGENT_DIR` and `PI_CODING_AGENT_SESSION_DIR` names apply only to a canonical Pi companion command; PI WEB never derives ambient environment-variable names from an arbitrary command. Use the explicit `PI_WEB_AGENT_*` names for alternate commands. `PI_WEB_AGENT_DIR` is an unconditional override, while a legacy `PI_CODING_AGENT_DIR` override stops applying when Settings selects an alternate command so the command and directory can transition together.
|
||||
|
||||
The session daemon resolves the persisted desired values plus its environment once at startup. That secret-free active profile stays fixed for the daemon lifetime. **Settings → Session daemon** saves command and directory together as desired configuration and shows whether the profile is active, needs a restart, or cannot be compared. Until the daemon restarts, sessions, Pi package operations, package-backed plugin discovery, status/install detection, and update planning continue to use the daemon-owned active profile; a web/API restart recovers that same active profile instead of applying the newly saved values.
|
||||
The session daemon resolves the persisted desired values plus its environment once at startup. That secret-free active profile stays fixed for the daemon lifetime. **Settings → Session daemon** saves command and directory together as desired configuration and shows whether the profile is active, needs a restart, or cannot be compared. Until the daemon restarts, sessions, Pi package operations, Pi-package-backed PI WEB plugin discovery, status/install detection, and update planning continue to use the daemon-owned active profile; a web/API restart recovers that same active profile instead of applying the newly saved values.
|
||||
|
||||
If the session daemon cannot report a valid active profile, profile-dependent package and plugin operations report unavailable instead of falling back to independently resolved config. A package-managed update command is shown only when PI WEB can preserve the active profile with a recognized, safe Pi companion CLI; otherwise the command is omitted. Remote profile editing likewise requires advertised support, and the gateway rejects a remote save if the target does not return the requested profile. Restart the session daemon on the selected machine to establish the next active profile.
|
||||
If the session daemon cannot report a valid active profile, profile-dependent Pi package and PI WEB plugin operations report unavailable instead of falling back to independently resolved config. A package-managed update command is shown only when PI WEB can preserve the active profile with a recognized, safe Pi companion CLI; otherwise the command is omitted. Remote profile editing likewise requires advertised support, and the gateway rejects a remote save if the target does not return the requested profile. Restart the session daemon on the selected machine to establish the next active profile.
|
||||
|
||||
### Pi extension provider baseline
|
||||
|
||||
This policy applies to **Pi runtime extensions**, not PI WEB browser plugins. Pi extensions are runtime modules loaded by the session daemon and can call `pi.registerProvider(...)`; PI WEB plugins are browser-side UI modules and never run in the session daemon.
|
||||
|
||||
PI WEB shares one model runtime across all sessions. When the session daemon starts, before any project resources load, it initializes global Pi extensions from the active agent profile (`agent.dir`), including extensions supplied by globally configured Pi packages. Provider registrations made by synchronous or awaited asynchronous extension factories during this bootstrap join the shared baseline. PI WEB captures both config-form registrations (`pi.registerProvider("id", config)`) and native-provider registrations (`pi.registerProvider(provider)`), alongside Pi built-ins, environment credentials, and providers from the active agent directory's `models.json`.
|
||||
|
||||
After startup capture, every later Pi extension provider registration, native registration, and unregistration is a no-op, regardless of source or provider ID. This includes global extensions replayed while sessions load, project extensions attempting to add or replace a provider, same-ID replacement or unregistration, lifecycle callbacks such as `session_start`, and `/reload`. The captured provider stays unchanged while non-provider Pi extension features continue to load and reload normally.
|
||||
|
||||
Ignored mutations are written to the session-daemon log once per operation and provider ID. The log entry contains no provider configuration or credentials, and PI WEB does not show a session warning or notification. This prevents accidental provider, configuration, or credential contamination between projects; it is not a security boundary because Pi extensions remain trusted daemon code.
|
||||
|
||||
Configure providers before the daemon starts: use the active agent directory's `models.json`, or install the Pi extension globally in that agent profile. Project Pi extensions and project-level `models.json` files cannot add providers to PI WEB's shared baseline. After updating PI WEB—or after installing, removing, or updating a global Pi extension that registers providers—manually restart `pi-web-sessiond.service` (`systemctl --user restart pi-web-sessiond`). Restarting only the web/API service and running `/reload` do not rebuild the baseline.
|
||||
|
||||
### Session daemon tools
|
||||
|
||||
|
||||
+26
-50
@@ -90,7 +90,7 @@
|
||||
<aside class="toc" aria-label="Plugin page contents">
|
||||
<strong>On this page</strong>
|
||||
<a href="#extend">What can be extended</a>
|
||||
<a href="#packages-vs-plugins">Pi packages vs PI WEB plugins</a>
|
||||
<a href="#packages-vs-plugins">Pi packages, extensions, and plugins</a>
|
||||
<a href="#ask-ai">What to ask AI to build</a>
|
||||
<a href="#example">Canonical example</a>
|
||||
<a href="#built-in-plugins">Built-in plugins</a>
|
||||
@@ -127,16 +127,22 @@
|
||||
</section>
|
||||
|
||||
<section id="packages-vs-plugins">
|
||||
<h2>Pi packages vs PI WEB plugins</h2>
|
||||
<h2>Pi packages, Pi extensions, and PI WEB plugins</h2>
|
||||
<p>
|
||||
<strong>Pi packages</strong> are packages managed by Pi (<code>pi install</code>, <code>pi remove</code>,
|
||||
<code>pi update</code>). A Pi package can provide extensions, skills, prompt templates, themes,
|
||||
context/system prompt files, and/or PI WEB browser plugins. Many Pi packages do not include a PI WEB plugin.
|
||||
<strong>Pi packages</strong> are distribution bundles managed by Pi (<code>pi install</code>,
|
||||
<code>pi remove</code>, <code>pi update</code>). A Pi package can provide Pi extensions, skills, prompt
|
||||
templates, themes, context/system prompt files, and/or PI WEB browser plugins. Many Pi packages do not
|
||||
include a PI WEB plugin.
|
||||
</p>
|
||||
<p>
|
||||
<strong>Pi extensions</strong> are runtime modules loaded by the session daemon. They can register Pi
|
||||
tools, hooks, commands, and model providers. They are not PI WEB plugins.
|
||||
</p>
|
||||
<p>
|
||||
<strong>PI WEB plugins</strong> are browser-side UI modules discovered from bundled, local, dev, and
|
||||
installed Pi-package sources. Enabling or disabling a PI WEB plugin is a PI WEB config task; installing,
|
||||
removing, or updating a Pi package is a Pi package-manager task.
|
||||
installed Pi-package sources. They cannot register model providers or server-side hooks. Enabling or
|
||||
disabling a PI WEB plugin is a PI WEB config task; installing, removing, or updating a Pi package is a
|
||||
separate Pi package-manager task.
|
||||
</p>
|
||||
<p>
|
||||
Use <strong>Settings → Pi packages</strong> to view configured Pi packages or install/remove/update a
|
||||
@@ -156,47 +162,16 @@
|
||||
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 <code>/reload</code> 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. For these ordinary resources, a routine session daemon restart is not required.
|
||||
Extension-provided global provider changes are the exception described below.
|
||||
</p>
|
||||
<h3 id="extension-provider-registrations">Extension provider registrations</h3>
|
||||
<p>
|
||||
PI WEB builds one provider baseline for the lifetime of the session daemon. At daemon startup, before any
|
||||
project resources load, it initializes globally installed, agent-dir extensions through Pi's
|
||||
session-services factory. Both config-form registrations
|
||||
(<code>pi.registerProvider("id", config)</code>) and native-provider registrations
|
||||
(<code>pi.registerProvider(provider)</code>) made during that initialization join the shared baseline,
|
||||
alongside Pi built-ins, environment credentials, and providers declared in the agent directory's
|
||||
<code>models.json</code>.
|
||||
unsupported or unavailable instead of silently falling back to the gateway.
|
||||
</p>
|
||||
<p>
|
||||
After startup capture, every extension provider registration, native registration, and unregistration is
|
||||
a no-op, regardless of source or provider ID. This includes global extensions replayed while sessions
|
||||
load, project extensions adding a provider or replacing a global provider with the same ID, late lifecycle
|
||||
calls such as <code>session_start</code>, and <code>/reload</code>. The captured provider remains unchanged,
|
||||
while non-provider extension features continue to load and reload normally.
|
||||
After installing, removing, or updating a Pi package, type <code>/reload</code> in each idle PI WEB
|
||||
session on the target machine to refresh ordinary Pi resources such as extensions, skills, prompt
|
||||
templates, themes, and context/system prompt files. Reload the browser page separately for newly
|
||||
discovered or changed PI WEB browser plugins. A provider-registering Pi extension follows a separate
|
||||
daemon-start policy; see
|
||||
<a href="config#pi-extension-provider-baseline">Pi extension provider baseline</a>.
|
||||
</p>
|
||||
<p>
|
||||
Ignored mutations are written to the session-daemon log once per operation and provider ID. These entries
|
||||
contain no provider configuration or credentials, and PI WEB does not show a session warning or
|
||||
notification. The policy prevents accidental provider, configuration, or credential contamination between
|
||||
projects; it is not a security boundary, because extensions remain trusted daemon code.
|
||||
</p>
|
||||
<p>
|
||||
Configure providers globally before the daemon starts: use the agent directory's
|
||||
<code>models.json</code>, or install the extension globally in the agent directory. Project-level
|
||||
<code>models.json</code> files do not add providers to PI WEB sessions.
|
||||
</p>
|
||||
<div class="callout warning">
|
||||
<strong>Restart required:</strong> after updating PI WEB, or after installing, removing, or updating a
|
||||
globally installed extension that registers providers, manually restart
|
||||
<code>pi-web-sessiond.service</code> (<code>systemctl --user restart pi-web-sessiond</code>). Restarting
|
||||
only the web/API service and running <code>/reload</code> do not recapture the baseline.
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="ask-ai">
|
||||
@@ -364,17 +339,18 @@ After editing, check the manifest endpoint and browser-console failure cases.</c
|
||||
<section id="manage-plugins">
|
||||
<h2>Manage PI WEB plugins</h2>
|
||||
<p>
|
||||
Open <strong>Settings → PI WEB plugins</strong> to review discovered bundled, local, dev, and Pi package
|
||||
plugins for the selected PI WEB machine. When the local machine is selected, this is the gateway plugin
|
||||
list; when a remote machine is selected, the list comes from that remote PI WEB server and includes
|
||||
Open <strong>Settings → PI WEB plugins</strong> to review discovered bundled, local, dev, and
|
||||
Pi-package-supplied PI WEB plugins for the selected PI WEB machine. When the local machine is selected,
|
||||
this is the gateway plugin list; when a remote machine is selected, the list comes from that remote PI WEB
|
||||
server and includes
|
||||
disabled discovered plugins it exposes. PI WEB can disable any discovered selected-machine plugin before
|
||||
the browser imports it. Core app contributions such as the command palette, base workspace tools, and
|
||||
themes are not managed through this plugin list.
|
||||
</p>
|
||||
<p>
|
||||
This surface is only for PI WEB plugin enablement. To install, remove, or update Pi packages that may
|
||||
provide plugins or other Pi resources, use <strong>Settings → Pi packages</strong>. In a federated setup,
|
||||
both the Pi packages panel and the PI WEB plugins panel target the selected machine; plugin enablement
|
||||
provide PI WEB plugins or other Pi resources, use <strong>Settings → Pi packages</strong>. In a federated
|
||||
setup, both the Pi packages panel and the PI WEB plugins panel target the selected machine; plugin enablement
|
||||
still writes the PI WEB <code>plugins</code> config key rather than changing Pi package-manager settings.
|
||||
</p>
|
||||
<div class="code-card">
|
||||
|
||||
+9
-15
@@ -13,27 +13,21 @@ Plugins can currently:
|
||||
|
||||
They do **not** run in the session daemon, do not get a server-side hook API, and are not sandboxed.
|
||||
|
||||
## Pi packages vs PI WEB plugins
|
||||
## Pi packages, Pi extensions, and PI WEB plugins
|
||||
|
||||
**Pi packages** are packages managed by Pi (`pi install`, `pi remove`, `pi update`). A Pi package can provide extensions, skills, prompt templates, themes, context/system prompt files, and/or PI WEB browser plugins. Many Pi packages do not include a PI WEB plugin.
|
||||
**Pi packages** are distribution bundles managed by Pi (`pi install`, `pi remove`, `pi update`). A Pi package can provide Pi extensions, skills, prompt templates, themes, context/system prompt files, and/or PI WEB browser plugins. Many Pi packages do not include a PI WEB plugin.
|
||||
|
||||
**PI WEB plugins** are browser-side PI WEB UI modules discovered from bundled, local, dev, and installed Pi-package sources. Enabling or disabling a PI WEB plugin is a PI WEB config task; installing, removing, or updating a Pi package is a Pi package-manager task.
|
||||
**Pi extensions** are runtime modules loaded by the session daemon. They can register Pi tools, hooks, commands, and model providers. They are not PI WEB plugins.
|
||||
|
||||
**PI WEB plugins** are browser-side UI modules discovered from bundled, local, dev, and installed Pi-package sources. They cannot register model providers or server-side hooks. Enabling or disabling a PI WEB plugin is a PI WEB config task; installing, removing, or updating a Pi package is a separate Pi package-manager task.
|
||||
|
||||
Use **Settings → Pi packages** to view configured Pi packages or install/remove/update a package. Enter only the package source, such as `npm:@scope/package`, a git/URL source, or a local path. PI WEB uses Pi's default package location, equivalent to `pi install <source>`, and does not ask for an install location.
|
||||
|
||||
When machine federation is enabled, **Settings → Pi packages** targets the currently selected machine. The panel labels whether changes will run on the local/gateway machine or on a selected remote PI WEB machine. If an older or unavailable remote PI WEB server does not expose package-management routes, PI WEB reports the package management operation as unsupported or unavailable instead of silently falling back to the gateway.
|
||||
|
||||
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. For these ordinary resources, a routine session daemon restart is not required. Extension-provided global provider changes are the exception described below.
|
||||
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.
|
||||
|
||||
## Extension provider registrations
|
||||
|
||||
PI WEB builds one provider baseline for the lifetime of the session daemon. At daemon startup, before any project resources load, it initializes globally installed (agent-dir) extensions through Pi's session-services factory. Both config-form registrations (`pi.registerProvider("id", config)`) and native-provider registrations (`pi.registerProvider(provider)`) made during that initialization join the shared baseline, alongside 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)).
|
||||
|
||||
After startup capture, every extension provider registration, native registration, and unregistration is a no-op, regardless of source or provider ID. This includes global extensions replayed while sessions load, project extensions adding a provider or replacing a global provider with the same ID, late lifecycle calls such as `session_start`, and `/reload`. The captured provider remains unchanged, while non-provider extension features continue to load and reload normally.
|
||||
|
||||
Ignored mutations are written to the session-daemon log once per operation and provider ID. These entries contain no provider configuration or credentials, and PI WEB does not show a session warning or notification. The policy prevents accidental provider, configuration, or credential contamination between projects; it is not a security boundary, because extensions remain trusted daemon code.
|
||||
|
||||
Configure providers globally before the daemon starts: use the agent directory's `models.json`, or install the extension globally in the agent directory. Project-level `models.json` files do not add providers to PI WEB sessions. **Restart required:** after updating PI WEB, or after installing, removing, or updating a globally installed extension that registers providers, manually restart `pi-web-sessiond.service` (`systemctl --user restart pi-web-sessiond`). Restarting only the web/API service and running `/reload` do not recapture the baseline.
|
||||
After installing, removing, or updating a Pi package, type `/reload` in each idle PI WEB session on the target machine to refresh ordinary Pi resources such as extensions, skills, prompt templates, themes, and context/system prompt files. Reload the browser page separately for newly discovered or changed PI WEB browser plugins. A provider-registering Pi extension follows a separate daemon-start policy; see [Pi extension provider baseline](https://pi-web.dev/config#pi-extension-provider-baseline).
|
||||
|
||||
## Trust model
|
||||
|
||||
@@ -179,9 +173,9 @@ If a remote plugin constructs absolute asset URLs, it should use the `pluginId`
|
||||
|
||||
## Manage PI WEB plugins
|
||||
|
||||
Open **Settings → PI WEB plugins** to review discovered bundled, local, dev, and Pi package plugins for the selected PI WEB machine. When the local machine is selected, this is the gateway plugin list; when a remote machine is selected, the list comes from that remote PI WEB server and includes disabled discovered plugins it exposes. PI WEB can disable any discovered selected-machine plugin before the browser imports it. Core app contributions such as the built-in command palette, base workspace tools, and themes are not managed through this plugin list.
|
||||
Open **Settings → PI WEB plugins** to review discovered bundled, local, dev, and Pi-package-supplied PI WEB plugins for the selected PI WEB machine. When the local machine is selected, this is the gateway plugin list; when a remote machine is selected, the list comes from that remote PI WEB server and includes disabled discovered plugins it exposes. PI WEB can disable any discovered selected-machine plugin before the browser imports it. Core app contributions such as the built-in command palette, base workspace tools, and themes are not managed through this plugin list.
|
||||
|
||||
This surface is only for PI WEB plugin enablement. To install, remove, or update Pi packages that may provide plugins or other Pi resources, use **Settings → Pi packages**. In a federated setup, both the Pi packages panel and the PI WEB plugins panel target the selected machine; plugin enablement still writes the PI WEB `plugins` config key rather than changing Pi package-manager settings.
|
||||
This surface is only for PI WEB plugin enablement. To install, remove, or update Pi packages that may provide PI WEB plugins or other Pi resources, use **Settings → Pi packages**. In a federated setup, both the Pi packages panel and the PI WEB plugins panel target the selected machine; plugin enablement still writes the PI WEB `plugins` config key rather than changing Pi package-manager settings.
|
||||
|
||||
Plugin preferences are stored under the top-level `plugins` config key in the PI WEB config file:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user