docs(webui): record the WebMCP deployment and error-shape traps

The module header now records the two ways the tools go silently missing: a
secure context is required, so a plain-HTTP dashboard exposes nothing even with
the origin-trial flag, and archie-ui embeds ui/dist, so rebuilding the bundle is
not deploying it and a stale process reports the tools as absent. It also
records that executeTool flattens a thrown execute error into a generic
UnknownError, which is why the confirm guard is pinned by a unit test rather
than by a browser run.
This commit is contained in:
sam committed 2026-09-22 14:00:42 +10:00
1 parent e7d9fa2c4c
commit 269fe87aea
1 file changed
+15
+15
View File
@@ -20,6 +20,21 @@
// not a name (a name fails with a TypeError).
// - `executeTool` returns the tool's result as a JSON string that parses to
// `{content:[{type:"text",text}]}`, not as the envelope object itself.
// A thrown `execute` error is also flattened by `executeTool` into a generic
// UnknownError, so its text cannot tell a rejected call from a failed one; a
// guard inside `execute` has to be pinned by a unit test, not by a browser run.
//
// Two deployment conditions make the tools silently absent, with no error:
// - `document.modelContext` needs a secure context. A dashboard served over
// plain HTTP (a LAN address, say) never exposes it, even with the
// origin-trial flag: `isSecureContext` is false and the API is undefined.
// Production terminates TLS in front of the dashboard; a plain-HTTP
// deployment gets no tools and no message saying so.
// - archie-ui embeds the built ui/dist into its binary, so rebuilding the
// dist is not deploying it. A running process keeps serving the bundle it
// embedded at build time, and a check against that stale process reports
// the tools as missing. Verify against a freshly built bundle, or restart
// the process.
//
// What the browser does not enforce, it should not appear to: see the
// annotation note in webmcp-tools.ts.