Archived
docs(sessions): document background catalog refresh and contain offline env window
Finding 6: serialize createOfflineModelRuntime so overlapping calls cannot interleave their PI_OFFLINE save/restore pairs and leave the process offline, and name the process-wide visibility of that window in the docblock. Finding 7: assert the offline construction through the public refresh seam via reloadConfig() — the request path that regressed — instead of reading upstream's private modelNetworkEnabled field. Finding 8.4/8.5: document the background provider-catalog refresh in docs/config.md and docs/config.html (cadence, timeout, single retry, offline opt-out via PI_WEB_OFFLINE / PI_OFFLINE only), and update the changeset to match the behavior after the earlier fixes.
This commit is contained in:
Federico Jaramillo Martinez
@@ -100,6 +100,7 @@
|
||||
<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="#catalog-refresh">Model catalog refresh</a>
|
||||
<a href="#session-tools">Session tools</a>
|
||||
<a href="#completion-tools">Completion tools</a>
|
||||
</aside>
|
||||
@@ -479,6 +480,17 @@
|
||||
<td>Not supported locally</td>
|
||||
<td>Restart web/API after env changes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Offline mode</td>
|
||||
<td>—</td>
|
||||
<td><code>PI_WEB_OFFLINE</code>, <code>PI_OFFLINE</code></td>
|
||||
<td>Web/API + session daemon env</td>
|
||||
<td>Not supported locally</td>
|
||||
<td>
|
||||
Restart session daemon and web/API after env changes; also disables the
|
||||
<a href="#catalog-refresh">background model catalog refresh</a>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
@@ -642,6 +654,45 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="catalog-refresh">
|
||||
<h2>Background model catalog refresh</h2>
|
||||
<p>
|
||||
PI WEB shares one model runtime across all sessions, and provider model catalogs are refreshed over the
|
||||
network only on the session daemon's own background schedule. Nothing a browser or API request triggers
|
||||
waits on a provider catalog fetch, so a slow or unreachable provider cannot stall opening the model
|
||||
selector, starting a session, or the auth dialogs.
|
||||
</p>
|
||||
<p>The session daemon runs the refresh:</p>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>15 seconds after the daemon starts</strong>, then <strong>hourly</strong>. Pi treats stored
|
||||
catalogs as fresh for four hours, so most hourly ticks make no network request at all; the shorter tick
|
||||
only makes sure a due refresh is not delayed to the next tick.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Immediately after a provider login or logout</strong>, bypassing that freshness window, because
|
||||
the cached catalog is known to be wrong.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
Each run is bounded: it is aborted after <strong>60 seconds</strong>, and a run that times out or fails
|
||||
earns <strong>one retry after five minutes</strong>. Failures never clear the stored catalogs — the last
|
||||
successfully fetched models stay in use and the daemon log records what failed. A refresh in flight is
|
||||
also aborted when the daemon shuts down.
|
||||
</p>
|
||||
<p>
|
||||
Models fetched by a background refresh appear the next time a client asks for the model list, so a model
|
||||
selector left open across a refresh may need to be reopened.
|
||||
</p>
|
||||
<p>
|
||||
To turn the background refresh off entirely, set <code>PI_WEB_OFFLINE</code> or <code>PI_OFFLINE</code> in
|
||||
the session daemon's environment and restart it. In offline mode PI WEB performs no provider catalog
|
||||
network requests, including after logins, and sessions use the catalogs already stored in the agent
|
||||
profile. The <code>PI_WEB_SKIP_VERSION_CHECK</code> and <code>PI_SKIP_VERSION_CHECK</code> keys do
|
||||
<strong>not</strong> affect this refresh; they only suppress PI WEB release checks.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section id="session-tools">
|
||||
<h2>Session daemon tools</h2>
|
||||
<h3><code>spawnSessions</code></h3>
|
||||
|
||||
@@ -131,6 +131,7 @@ Rows with JSON key `—` are runtime-only environment variables, not config-file
|
||||
| Agent profile session storage directory | — | `PI_WEB_AGENT_SESSION_DIR` (`PI_CODING_AGENT_SESSION_DIR` for Pi compatibility) | Session daemon env | Not supported locally | Restart session daemon; env-only session storage override |
|
||||
| Agent profile state directory | — | `PI_WEB_AGENT_DIR` (`PI_CODING_AGENT_DIR` for Pi compatibility) | Web/API + session daemon env | Not supported locally | Restart services |
|
||||
| Skip update checks | — | `PI_WEB_SKIP_VERSION_CHECK`, `PI_WEB_OFFLINE`, `PI_SKIP_VERSION_CHECK`, `PI_OFFLINE` | Web/API env | Not supported locally | Restart web/API after env changes |
|
||||
| Offline mode | — | `PI_WEB_OFFLINE`, `PI_OFFLINE` | Web/API + session daemon env | Not supported locally | Restart session daemon and web/API after env changes; also disables the [background model catalog refresh](#background-model-catalog-refresh) |
|
||||
|
||||
## Key details
|
||||
|
||||
@@ -218,6 +219,21 @@ Ignored mutations are written to the session-daemon log once per operation and p
|
||||
|
||||
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.
|
||||
|
||||
### Background model catalog refresh
|
||||
|
||||
PI WEB shares one model runtime across all sessions, and provider model catalogs are refreshed over the network only on the session daemon's own background schedule. Nothing a browser or API request triggers waits on a provider catalog fetch, so a slow or unreachable provider cannot stall opening the model selector, starting a session, or the auth dialogs.
|
||||
|
||||
The session daemon runs the refresh:
|
||||
|
||||
- **15 seconds after the daemon starts**, then **hourly**. Pi treats stored catalogs as fresh for four hours, so most hourly ticks make no network request at all; the shorter tick only makes sure a due refresh is not delayed to the next tick.
|
||||
- **Immediately after a provider login or logout**, bypassing that freshness window, because the cached catalog is known to be wrong.
|
||||
|
||||
Each run is bounded: it is aborted after **60 seconds**, and a run that times out or fails earns **one retry after five minutes**. Failures never clear the stored catalogs — the last successfully fetched models stay in use and the daemon log records what failed. A refresh in flight is also aborted when the daemon shuts down.
|
||||
|
||||
Models fetched by a background refresh appear the next time a client asks for the model list, so a model selector left open across a refresh may need to be reopened.
|
||||
|
||||
To turn the background refresh off entirely, set `PI_WEB_OFFLINE` or `PI_OFFLINE` in the session daemon's environment and restart it. In offline mode PI WEB performs no provider catalog network requests, including after logins, and sessions use the catalogs already stored in the agent profile. The `PI_WEB_SKIP_VERSION_CHECK` and `PI_SKIP_VERSION_CHECK` keys do **not** affect this refresh; they only suppress PI WEB release checks.
|
||||
|
||||
### Session daemon tools
|
||||
|
||||
`spawnSessions` controls whether agents receive the `spawn_session` tool. It defaults to `true`; set it to `false` if you do not want an agent to start independent PI WEB sessions.
|
||||
|
||||
Reference in New Issue
Block a user