Archived
feat: add Pi package management settings
This commit is contained in:
Federico Jaramillo Martinez
+15
-7
@@ -80,8 +80,8 @@
|
||||
<h1>Configure PI WEB where your agents work.</h1>
|
||||
<p>
|
||||
PI WEB configuration covers the machine-local and project-local settings you usually need: bind address,
|
||||
trusted development-host settings, UI preferences, plugin enablement, file-explorer path access, upload
|
||||
limits, and session-daemon tools.
|
||||
trusted development-host settings, UI preferences, PI WEB plugin enablement, file-explorer path access,
|
||||
upload limits, and session-daemon tools.
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
@@ -112,6 +112,12 @@
|
||||
Each PI WEB machine has its own config. When using Fleet/machine federation, edit a remote machine's
|
||||
config by opening that machine directly or changing files on that machine.
|
||||
</p>
|
||||
<p>
|
||||
Pi package settings are separate from PI WEB config. They live in Pi's package-manager settings and are
|
||||
managed by Pi (<code>pi install</code>, <code>pi remove</code>, <code>pi update</code>) or
|
||||
<strong>Settings → Pi packages</strong>. The PI WEB <code>plugins</code> config key only enables or
|
||||
disables discovered PI WEB browser plugins.
|
||||
</p>
|
||||
<p>
|
||||
If you installed services with a custom config path, rerun
|
||||
<code>pi-web install --config /path/to/config.json</code> after changing that path or after upgrading from
|
||||
@@ -136,7 +142,8 @@
|
||||
<li><code>maxUploadBytes</code>: restart both the web/API process and the session daemon.</li>
|
||||
<li><code>spawnSessions</code> / <code>subsessions</code>: restart the session daemon.</li>
|
||||
<li><code>pathAccess</code>: applies on the next request; existing file views may need a browser refresh.</li>
|
||||
<li><code>plugins</code>: reload the browser tab after changing plugin enablement.</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, reload the browser page for newly discovered PI WEB browser plugins and reload existing Pi sessions (or use <code>/reload</code> in Pi) for session-runtime resources. A routine session daemon restart is not required.</li>
|
||||
<li><code>shortcuts</code>: saved settings apply in the browser after config refresh/save.</li>
|
||||
</ul>
|
||||
</section>
|
||||
@@ -144,9 +151,10 @@
|
||||
<section id="global-config">
|
||||
<h2>Global config example</h2>
|
||||
<p>
|
||||
<code>pi-web install</code> creates the initial file. You can also save settings from
|
||||
<strong>Settings → General</strong>, <strong>Settings → Plugins</strong>, <strong>Settings → Keyboard</strong>,
|
||||
and <strong>Settings → Session daemon</strong>.
|
||||
<code>pi-web install</code> creates the initial file. You can also save PI WEB config settings from
|
||||
<strong>Settings → General</strong>, <strong>Settings → PI WEB plugins</strong>,
|
||||
<strong>Settings → Keyboard</strong>, and <strong>Settings → Session daemon</strong>. Pi package operations
|
||||
live separately under <strong>Settings → Pi packages</strong>.
|
||||
</p>
|
||||
<div class="code-card">
|
||||
<div class="copy-row">
|
||||
@@ -279,7 +287,7 @@
|
||||
<td>Restart session daemon</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Plugin enablement/settings</td>
|
||||
<td>PI WEB plugin enablement/settings</td>
|
||||
<td><code>plugins.<id>.enabled</code>, <code>plugins.<id>.settings</code></td>
|
||||
<td>—</td>
|
||||
<td>Global</td>
|
||||
|
||||
+6
-1
@@ -13,6 +13,8 @@ PI WEB uses two config files:
|
||||
|
||||
Each PI WEB machine has its own config. When using Fleet/machine federation, edit a remote machine's config by opening that machine directly or changing files on that machine.
|
||||
|
||||
Pi package settings are separate from PI WEB config. They live in Pi's package-manager settings and are managed by Pi (`pi install`, `pi remove`, `pi update`) or **Settings → Pi packages**. The PI WEB `plugins` config key only enables or disables discovered PI WEB browser plugins.
|
||||
|
||||
If you installed services with a custom config path, rerun `pi-web install --config /path/to/config.json` after changing that path or after upgrading from a version that only applied the custom path to the web service. This regenerates service files so the web/API and session daemon use the same `PI_WEB_CONFIG`.
|
||||
|
||||
## Precedence and reloads
|
||||
@@ -34,7 +36,8 @@ Process restarts depend on the key:
|
||||
- `spawnSessions` / `subsessions`: restart the session daemon.
|
||||
- `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 plugin enablement.
|
||||
- `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, reload the browser page for newly discovered PI WEB browser plugins and reload existing Pi sessions (or use `/reload` in Pi) for session-runtime resources. A routine session daemon restart is not required.
|
||||
- `shortcuts`: saved settings apply in the browser after config refresh/save.
|
||||
|
||||
## Global config example
|
||||
@@ -170,6 +173,8 @@ Tracked subsessions let an agent delegate work to child sessions, get notified w
|
||||
|
||||
### Plugin config
|
||||
|
||||
The `plugins` key is only for PI WEB browser plugin enablement/settings. It does not install, remove, or update Pi packages; use **Settings → Pi packages** or Pi's package manager for package operations.
|
||||
|
||||
Plugins are enabled by default. Set `plugins.<id>.enabled` to `false` to remove a plugin from `/pi-web-plugins/manifest.json` before the browser imports it.
|
||||
|
||||
```json
|
||||
|
||||
+2
-1
@@ -281,7 +281,8 @@
|
||||
</div>
|
||||
<p>
|
||||
Use <strong>Settings → General</strong> for host, port, and external filesystem roots; <strong>Settings → Session daemon</strong>
|
||||
for agent-spawn tools; <strong>Settings → Plugins</strong> for plugin enablement; and <strong>Settings → Keyboard</strong>
|
||||
for agent-spawn tools; <strong>Settings → Pi packages</strong> for Pi package install/remove/update;
|
||||
<strong>Settings → PI WEB plugins</strong> for browser plugin enablement; and <strong>Settings → Keyboard</strong>
|
||||
for shortcut overrides.
|
||||
</p>
|
||||
<div class="callout">
|
||||
|
||||
+39
-7
@@ -90,10 +90,11 @@
|
||||
<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="#ask-ai">What to ask AI to build</a>
|
||||
<a href="#example">Canonical example</a>
|
||||
<a href="#built-in-plugins">Built-in plugins</a>
|
||||
<a href="#manage-plugins">Manage plugins</a>
|
||||
<a href="#manage-plugins">Manage PI WEB plugins</a>
|
||||
<a href="#remote-machine-plugins">Remote machine plugins</a>
|
||||
<a href="#production">Production usage</a>
|
||||
<a href="#agent-docs">AI-friendly docs</a>
|
||||
@@ -125,6 +126,33 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="packages-vs-plugins">
|
||||
<h2>Pi packages vs 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, and/or
|
||||
PI WEB browser plugins. Many Pi packages do not include a PI WEB plugin.
|
||||
</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.
|
||||
</p>
|
||||
<p>
|
||||
Use <strong>Settings → Pi packages</strong> to view configured Pi packages or install/remove/update a
|
||||
package. Enter only the package source, such as <code>npm:@scope/package</code>, a git/URL source, or a
|
||||
local path. PI WEB uses Pi's default package location, equivalent to <code>pi install <source></code>,
|
||||
and does not ask for an install location.
|
||||
</p>
|
||||
<p>
|
||||
Use <strong>Settings → PI WEB plugins</strong> to enable or disable discovered PI WEB browser plugins
|
||||
before the browser imports them. After installing, removing, or updating a Pi package, reload the browser
|
||||
page to import newly discovered PI WEB browser plugins. Reload existing Pi sessions, or use
|
||||
<code>/reload</code> in Pi, so extensions, skills, prompt templates, and themes are rediscovered. A
|
||||
routine session daemon restart is not required.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section id="ask-ai">
|
||||
<h2>What to ask AI to build</h2>
|
||||
<p>
|
||||
@@ -204,7 +232,7 @@ After editing, check the manifest endpoint and browser-console failure cases.</c
|
||||
plugins appear in <code>/pi-web-plugins/manifest.json</code>.
|
||||
</p>
|
||||
<p>
|
||||
Built-in plugins can be managed from <strong>Settings → Plugins</strong> or with the top-level
|
||||
Built-in plugins can be managed from <strong>Settings → PI WEB plugins</strong> or with the top-level
|
||||
<code>plugins</code> config key.
|
||||
</p>
|
||||
|
||||
@@ -285,12 +313,16 @@ After editing, check the manifest endpoint and browser-console failure cases.</c
|
||||
</section>
|
||||
|
||||
<section id="manage-plugins">
|
||||
<h2>Manage plugins</h2>
|
||||
<h2>Manage PI WEB plugins</h2>
|
||||
<p>
|
||||
Open <strong>Settings → Plugins</strong> to review discovered bundled, local, dev, and Pi package plugins
|
||||
for the PI WEB gateway you opened. PI WEB can disable any discovered 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.
|
||||
Open <strong>Settings → PI WEB plugins</strong> to review discovered bundled, local, dev, and Pi package
|
||||
plugins for the PI WEB gateway you opened. PI WEB can disable any discovered 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>.
|
||||
</p>
|
||||
<div class="code-card">
|
||||
<div class="copy-row">
|
||||
|
||||
+18
-6
@@ -13,6 +13,16 @@ 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** are packages managed by Pi (`pi install`, `pi remove`, `pi update`). A Pi package can provide extensions, skills, prompt templates, themes, 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.
|
||||
|
||||
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.
|
||||
|
||||
Use **Settings → PI WEB plugins** to enable or disable discovered PI WEB browser plugins before the browser imports them. After installing, removing, or updating a Pi package, reload the browser page to import newly discovered PI WEB browser plugins. Reload existing Pi sessions, or use `/reload` in Pi, so session-runtime resources such as extensions, skills, prompt templates, and themes are rediscovered. A routine session daemon restart is not required.
|
||||
|
||||
## Trust model
|
||||
|
||||
Plugins run as JavaScript in the browser app. Treat them as trusted code:
|
||||
@@ -155,9 +165,11 @@ const url = new URL("./asset.json", import.meta.url);
|
||||
|
||||
If a remote plugin constructs absolute asset URLs, it should use the `pluginId` from `activate()` because PI WEB gives remote plugins a gateway-scoped runtime id. Hard-coded `/pi-web-plugins/<original-id>/...` URLs may point at the gateway instead of the remote machine.
|
||||
|
||||
## Manage plugins
|
||||
## Manage PI WEB plugins
|
||||
|
||||
Open **Settings → Plugins** to review discovered bundled, local, dev, and Pi package plugins for the PI WEB gateway you opened. PI WEB can disable any discovered gateway 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 plugins for the PI WEB gateway you opened. PI WEB can disable any discovered gateway 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**.
|
||||
|
||||
Plugin preferences are stored under the top-level `plugins` config key in the PI WEB config file:
|
||||
|
||||
@@ -183,14 +195,14 @@ After changing plugin enablement, reload the PI WEB browser tab. Already-loaded
|
||||
|
||||
PI WEB ships core, discoverable plugins in the main `@jmfederico/pi-web` npm package. No separate `pi install` step is required: update PI WEB, reload the browser tab, and the bundled plugins appear in `/pi-web-plugins/manifest.json`.
|
||||
|
||||
Built-in plugins can be managed from **Settings → Plugins** or with the top-level `plugins` config key.
|
||||
Built-in plugins can be managed from **Settings → PI WEB plugins** or with the top-level `plugins` config key.
|
||||
|
||||
### Updates
|
||||
|
||||
**Plugin id:** `updates`
|
||||
**What it does:** adds a conditional **Updates** workspace tab with PI WEB update, restart, and installed-service guidance.
|
||||
|
||||
Updates is enabled by default. It declares `machineSpecific: true` so the gateway Updates tab only appears for the local machine; while a remote machine is selected, that remote machine's Updates plugin is used if available. To hide it, disable `updates` in **Settings → Plugins** or set:
|
||||
Updates is enabled by default. It declares `machineSpecific: true` so the gateway Updates tab only appears for the local machine; while a remote machine is selected, that remote machine's Updates plugin is used if available. To hide it, disable `updates` in **Settings → PI WEB plugins** or set:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -206,7 +218,7 @@ Updates is enabled by default. It declares `machineSpecific: true` so the gatewa
|
||||
**Config file:** `.pi-web/tasks.json`
|
||||
**What it does:** adds a **Tasks** workspace tab for running configured shell commands in dedicated PI WEB terminals.
|
||||
|
||||
Workspace Tasks is enabled by default. To hide it, disable `workspace-tasks` in **Settings → Plugins** or set:
|
||||
Workspace Tasks is enabled by default. To hide it, disable `workspace-tasks` in **Settings → PI WEB plugins** or set:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -273,7 +285,7 @@ PI WEB builds the gateway `/pi-web-plugins/manifest.json` from these sources:
|
||||
|
||||
Entries may be real directories or symlinks. This is the recommended development workflow.
|
||||
|
||||
3. Installed Pi packages that expose PI WEB plugin metadata. Pi packages may be user or project scoped.
|
||||
3. Installed Pi packages that expose PI WEB plugin metadata. Pi packages may be user or project scoped. Installing/removing/updating Pi packages is done from **Settings → Pi packages** (or Pi's package manager), not from the PI WEB plugin enable/disable list.
|
||||
|
||||
Remote machines expose their own manifests through the gateway at `/api/machines/<machine-id>/pi-web-plugins/manifest.json`. Those plugin modules are rewritten to gateway-scoped asset URLs and registered under machine-scoped runtime ids so duplicate plugin ids on different machines do not collide.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user