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
+27
View File
@@ -91,6 +91,7 @@
<strong>On this page</strong>
<a href="#extend">What can be extended</a>
<a href="#packages-vs-plugins">Pi packages, extensions, and plugins</a>
<a href="#pi-extension-dialogs">Pi extension dialogs</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>
@@ -174,6 +175,32 @@
</p>
</section>
<section id="pi-extension-dialogs">
<h2>Pi extension dialogs in PI WEB</h2>
<p>
Pi extensions running under PI WEB's session daemon can ask the user questions with
<code>ctx.ui.confirm()</code>, <code>ctx.ui.select()</code>, and <code>ctx.ui.input()</code>. For these
three methods <code>ctx.hasUI</code> is true in fact: the call renders a dialog card inline in the
session transcript — including from <code>session_start</code> hooks while the session is still starting
and from in-flight <code>tool_call</code> hooks — and resolves with the user's actual answer.
</p>
<p>
Answers travel over a dedicated session-daemon channel, never the prompt queue, so a parked
<code>tool_call</code> hook cannot deadlock the run. Open dialogs survive browser reloads, the first
answer wins across tabs, and unanswered dialogs settle safely: aborting the run or replacing the runtime
resolves them immediately with the kind's cancel value (<code>false</code> for confirm,
<code>undefined</code> for select and input), and the effective deadline — the sooner of the extension's
own <code>timeout</code> and the daemon's <code>extensionDialogsTimeoutMs</code> safety valve (default 5
minutes, <code>0</code> waits forever) — does the same when no one answers. Other
<code>ExtensionUIContext</code> surfaces (widgets, status, editor, <code>custom</code>) remain no-ops
despite <code>hasUI === true</code>.
</p>
<p>
For the full behavior notes and author guidance, read <a href="plugins.md">plugins.md</a>; for the
timeout key, see <a href="config#extension-dialogs">Extension dialogs</a> in the configuration reference.
</p>
</section>
<section id="ask-ai">
<h2>What to ask AI to build</h2>
<p>