snowspeeder/pi-web
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document immutable provider bootstrap

Browse Source
This commit is contained in:
Federico Jaramillo Martinez
2026-07-22 20:46:41 +02:00
parent 66f0ea44ce
commit ee8d9e5359
8 changed files with 49 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plugins.html
+34 -7
View File
@@ -160,16 +160,43 @@
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. A routine session daemon restart is not required.
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>.
</p>
<p>
One exception applies to Pi package extensions: PI WEB providers come from global sources only
(Pi built-ins, environment credentials, the agent directory's <code>models.json</code>, and providers
registered by globally installed, agent-dir extensions). If a project extension calls
<code>pi.registerProvider</code>, PI WEB ignores the registration and warns in the session; everything
else the extension registers keeps working. Move such a provider to a global source: declare it in
the agent directory's <code>models.json</code>, or install the extension globally.
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.
</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">