@khanglvm/relay 0.13.3 → 0.13.5

package/README.md

@@ -61,10 +61,11 @@ rly mcp config
 
 When the agent calls a relay tool, the host renders relay's `ui://relay/board`
 resource in a sandboxed iframe, hands it the board spec, and the user's answers
-flow back to the agent over the bridge (`ui/update-model-context`) — markdown,
-code, diffs, tables, charts, mermaid/graphviz diagrams, images, and forms, all
-in-chat. The classic browser board (`rly ask` / `rly show`) is unchanged; pick
-whichever surface fits.
+flow back to the agent as a `ui/message` user turn, with
+`ui/update-model-context` used as a best-effort structured context sync —
+markdown, code, diffs, tables, charts, mermaid/graphviz diagrams, images, and
+forms, all in-chat. The classic browser board (`rly ask` / `rly show`) is
+unchanged; pick whichever surface fits.
 
 ## What it improves
 
@@ -114,10 +115,11 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 - **Same board, postMessage transport.** The inline board reuses relay's block
   renderer (markdown, code, diff, table, chart, mermaid, graphviz, image, html)
   over the MCP Apps JSON-RPC bridge: the spec arrives as the tool result, the
-  user's answers go back via `ui/update-model-context`, the iframe auto-sizes
-  via `ui/notifications/size-changed`, and vendored Chart.js / Mermaid / Viz.js
-  load on demand through the host's `resources/read` (no `/vendor` route, no
-  server in the sandbox).
+  user's submit goes back via `ui/message` so the agent resumes, the structured
+  payload is also offered through `ui/update-model-context`, the iframe
+  auto-sizes via `ui/notifications/size-changed`, and vendored Chart.js /
+  Mermaid / Viz.js load on demand through the host's `resources/read` (no
+  `/vendor` route, no server in the sandbox).
 - **One-command setup** — `rly mcp install --target claude|codex` writes the
   host config; `rly mcp config` prints the snippet for any MCP host. The classic
   browser board is untouched.

package/docs/AGENT.md

@@ -111,7 +111,8 @@ finalizes when your call completes — so the user sees it build, not a blank wa
 Both take **the exact same board spec** documented below (the tool `inputSchema`
 *is* this spec). Call the tool with your spec; the host shows the board, the user
 fills it in, and their answers come back to you (answers, per-question notes,
-comment) — read them just as you would the CLI's result JSON. There is **no
+comment) as a user-message turn, with structured context synced when the host
+supports it — read them just as you would the CLI's result JSON. There is **no
 `--detach`/`rly wait` dance, no stdout parsing, and no timeout** in this mode; the
 board stays live until the user submits and the host delivers the result.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "description": "Question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "keywords": [
     "ai-agents",

package/src/mcp-ui/board.js

@@ -4,8 +4,9 @@
 // host app (Claude desktop/mobile, Codex, …) as a sandboxed inline iframe.
 // There is no local HTTP server here: every exchange with the host travels over
 // JSON-RPC on window.postMessage — the spec arrives as the tool result, the
-// user's answers go back via `ui/update-model-context`, and vendored libraries
-// (Chart.js / Mermaid / Viz.js) are pulled through the host's `resources/read`.
+// user's final submission goes back as a `ui/message` user turn, and vendored
+// libraries (Chart.js / Mermaid / Viz.js) are pulled through the host's
+// `resources/read`.
 //
 // Rich blocks are rendered by the SAME window.RelayBlocks as the browser board
 // (markdown, code, diff, table, chart, mermaid, graphviz, image, html), so the
@@ -957,19 +958,30 @@
       annotations: data.annotations,
     };
     const text = summarize(data);
-    let delivered = false;
+    let messageDelivered = false;
+    let contextDelivered = false;
     try {
+      // A completed relay form is a user reply, not passive context. Some hosts
+      // ACK `ui/update-model-context` without starting a new model turn, so send
+      // the transcript as a user message first to wake the agent reliably.
+      await request('ui/message', { role: 'user', content: { type: 'text', text } });
+      messageDelivered = true;
+    } catch {
+      // Older/leaner hosts may not expose app-initiated messages.
+    }
+    try {
+      // Keep the structured payload available to hosts that attach app context.
+      // This is best-effort because context updates are intentionally silent.
       await request('ui/update-model-context', { content: [{ type: 'text', text }], structuredContent: structured });
-      delivered = true;
+      contextDelivered = true;
     } catch {
-      // Fallback for hosts without update-model-context: post a chat message.
-      try { await request('ui/message', { role: 'user', content: { type: 'text', text } }); delivered = true; } catch { /* give up gracefully */ }
+      // If ui/message worked, the agent still receives the submission transcript.
     }
     submitted = true;
-    showDone(delivered);
+    showDone(messageDelivered, contextDelivered);
   }
 
-  function showDone(delivered) {
+  function showDone(messageDelivered, contextDelivered) {
     // Collapse: leave fullscreen, drop the whole form for a one-line confirmation
     // so the host shrinks the iframe to a small footprint in the transcript.
     if (Annotate) { try { Annotate.teardown(); } catch { /* nothing to tear down */ } }
@@ -977,8 +989,10 @@
     app.replaceChildren(el('div', { class: 'mcp-done' },
       el('span', { class: 'mark' }, '✓'),
       el('span', { class: 'lead' }, QS.length ? 'Submitted' : 'Acknowledged'),
-      el('span', { class: 'sub' }, delivered
+      el('span', { class: 'sub' }, messageDelivered
         ? '· sent back to the agent'
+        : contextDelivered
+          ? '· saved; send the agent a message to continue'
         : '· tell the agent you’ve responded')));
     // Report the small height immediately, then again next frame / after layout
     // settles — beats hosts that only grow on debounced size events.

package/src/mcp.js

@@ -8,8 +8,8 @@
 //   • the tools `relay_ask` / `relay_show` link to it via _meta.ui.resourceUri
 //   • calling a tool returns the (normalized) board spec as structuredContent;
 //     the host renders the resource in a sandboxed iframe and forwards the spec
-//   • the iframe collects the user's answers and sends them back to the model
-//     via `ui/update-model-context`
+//   • the iframe collects the user's answers and sends them back as a user
+//     message; it also syncs model context when the host supports it
 //
 // Framing is the MCP stdio transport: newline-delimited JSON-RPC, one message
 // per line, never embedded newlines. stdout carries ONLY protocol messages;
@@ -156,7 +156,7 @@ function buildResult(method, params, clientProtocol) {
         },
         serverInfo: { name: 'relay', version: PKG.version },
         instructions:
-          'relay renders interactive boards inline. Call relay_ask to collect decisions/feedback with real form controls, or relay_show to present plans/diagrams/data — instead of asking in plain text. Read the user\'s answers from the structuredContent that returns after they submit.',
+          'relay renders interactive boards inline. Call relay_ask to collect decisions/feedback with real form controls, or relay_show to present plans/diagrams/data — instead of asking in plain text. When the user submits, relay sends their answers back as a user message so the agent continues.',
       };
     case 'ping':
       return {};
@@ -198,9 +198,10 @@ function readResource(params) {
 
 // A tool call: normalize the spec and hand it to the host as structuredContent.
 // The host renders ui://relay/board and forwards this spec to the iframe, which
-// collects the answers and returns them via ui/update-model-context. Spec errors
-// come back as an isError tool result (not a protocol error) so the model can
-// see and fix them.
+// collects the answers and returns them via a UI-originated user message (with
+// ui/update-model-context as a best-effort context sync). Spec errors come back
+// as an isError tool result (not a protocol error) so the model can see and fix
+// them.
 function callTool(params) {
   const name = params && params.name;
   if (name !== 'relay_ask' && name !== 'relay_show') {

package/src/server.js

@@ -694,13 +694,22 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   });
 
   // Bind the requested port (reopen/rescue reuse the board's last port so a
-  // still-open tab reconnects). If that port was grabbed by another process in
-  // the meantime, fall back to a random free one rather than failing to boot.
+  // still-open tab reconnects). A board just stopped on that port holds its
+  // listening socket through a short close grace, so a stop-then-reopen on the
+  // same port can briefly hit EADDRINUSE — retry for ~2s to ride that out before
+  // giving up. Only then fall back to a random free port rather than failing.
   await new Promise((resolve, reject) => {
+    const RETRY_MS = 200;
+    const MAX_RETRIES = 10; // ~2s — covers a prior server's ~600ms close grace
+    let retries = 0;
     const bind = (p, allowFallback) => {
       const onErr = (e) => {
         if (allowFallback && e && e.code === 'EADDRINUSE' && p !== 0) {
-          bind(0, false); // desired port busy → random free one
+          if (retries++ < MAX_RETRIES) {
+            setTimeout(() => bind(p, true), RETRY_MS); // port freeing up — retry it
+          } else {
+            bind(0, false); // still busy after retries → random free port
+          }
         } else {
           reject(e);
         }