docs: document Pi extension dialogs and extensionDialogsTimeoutMs

Add the close-out documentation for extension dialog support:

- docs/config.md (+ synchronized config.html): extensionDialogsTimeoutMs
  in the config matrix, reload/restart guidance, the global config
  example, and a new Extension dialogs key-detail section covering the
  unattended-dialog safety valve (default 5 min, 0 = forever, effective
  deadline is the sooner of the extension's own timeout and this knob).
- docs/plugins.md (+ synchronized plugins.html): new Pi extension
  dialogs in PI WEB behavior note for extension authors — confirm/select/
  input render inline in the transcript and resolve with the real answer,
  answers use a dedicated daemon channel (never the prompt queue, so
  tool_call hooks park safely), session_start dialogs are reachable
  during create and open, reload rehydration, first-answer-wins across
  tabs, abort/runtime-replacement settlement, and the reload-mid-startup
  browser-local caveat.
- Add the extension-dialogs changeset (patch) for the release notes.
This commit is contained in:
Federico Jaramillo Martinez
2026-07-29 07:52:21 +02:00
parent 346607e8bc
commit 5759201a39
5 changed files with 93 additions and 2 deletions
+37 -1
View File
@@ -102,6 +102,7 @@
<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="#extension-dialogs">Extension dialogs</a>
<a href="#completion-tools">Completion tools</a>
</aside>
@@ -173,7 +174,7 @@
<ul>
<li><code>host</code> / <code>port</code>: restart the gateway web/API service or process.</li>
<li><code>maxUploadBytes</code>: restart both the web/API process and the session daemon on that machine.</li>
<li><code>agent.command</code> / <code>agent.dir</code> / <code>spawnSessions</code> / <code>subsessions</code> / <code>askUser</code>: restart the session daemon on that machine.</li>
<li><code>agent.command</code> / <code>agent.dir</code> / <code>spawnSessions</code> / <code>subsessions</code> / <code>askUser</code> / <code>extensionDialogsTimeoutMs</code>: restart the session daemon on that machine.</li>
<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>
@@ -213,6 +214,7 @@
"spawnSessions": true,
"subsessions": false,
"askUser": true,
"extensionDialogsTimeoutMs": 300000,
"plugins": {
"workspace-tasks": { "enabled": true },
"updates": { "enabled": true },
@@ -376,6 +378,14 @@
<td>Not supported locally</td>
<td>Restart session daemon on that machine</td>
</tr>
<tr>
<td>Extension dialog auto-cancel timeout</td>
<td><code>extensionDialogsTimeoutMs</code></td>
<td></td>
<td>Global/session daemon</td>
<td>Not supported locally</td>
<td>Restart session daemon on that machine</td>
</tr>
<tr>
<td>PI WEB plugin enablement/settings</td>
<td><code>plugins.&lt;id&gt;.enabled</code>, <code>plugins.&lt;id&gt;.settings</code></td>
@@ -842,6 +852,32 @@
</div>
</section>
<section id="extension-dialogs">
<h2>Extension dialogs</h2>
<p>
Pi extensions can ask the user questions from <code>ctx.ui.confirm()</code>,
<code>ctx.ui.select()</code>, and <code>ctx.ui.input()</code> — including from
<code>session_start</code> hooks and in-flight <code>tool_call</code> hooks. PI WEB renders these dialogs
inline in the session transcript and answers them through a dedicated session-daemon channel, never the
prompt queue, so a dialog parked inside a <code>tool_call</code> hook cannot deadlock the run. Dialog
support is always on; there is no enable flag. See
<a href="plugins#pi-extension-dialogs">Pi extension dialogs in PI WEB</a> for behavior details and author
guidance.
</p>
<p>
<code>extensionDialogsTimeoutMs</code> is the unattended-dialog safety valve: how long the session daemon
waits for an answer before settling the dialog with its kind's cancel value (<code>false</code> for
confirm, <code>undefined</code> for select and input). It defaults to <code>300000</code> (5 minutes);
set it to <code>0</code> to wait forever. An extension's own <code>timeout</code> option still applies,
and the effective deadline is the sooner of the two.
</p>
<div class="callout warning">
<strong>Restart required:</strong> <code>extensionDialogsTimeoutMs</code> is edited directly in the global
config file. Restart the session daemon after changing it — for the systemd user service, run
<code>systemctl --user restart pi-web-sessiond</code>.
</div>
</section>
<section id="completion-tools">
<h2>Optional completion tools</h2>