@khanglvm/relay 0.13.1 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "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/skills/relay/SKILL.md

@@ -417,6 +417,18 @@ the matching `answers` value (e.g. `answers.approach = "a"` but
 `notes.approach = "actually B"` → the user means B). Reconcile them before
 generating output. The same channels appear under `draft` on timeout/cancel.
 
+**Don't let your shell truncate the result.** A board with several annotations
+prints a large JSON blob, and most agent shell tools cap stdout — so you silently
+get only the first few annotations and miss the rest. Two rules:
+
+- **Never pipe `rly wait`/`rly result` through `head`/`tail`/`sed`** (or any
+  output cap). That's exactly how annotations get dropped.
+- The full result is **always written to a file**, surfaced as the FIRST field
+  of the output: `"resultFile": "~/.relay/boards/<id>.result.json"`. If the
+  output looks cut off (or to be safe on any board with annotations), **read
+  that file with your file tool** instead of trusting stdout — it's the complete,
+  untruncated payload.
+
 ### Reply to annotations (agent → user conversation)
 
 ```sh

package/src/cli.js

@@ -15,6 +15,7 @@ import {
   loadRunning,
   removeRunning,
   isAlive,
+  saveResultFile,
   HOME,
 } from './store.js';
 import { runBoard } from './server.js';
@@ -76,6 +77,17 @@ function printJson(obj) {
   process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
 }
 
+// Print a terminal result. A board with many annotations produces a large JSON
+// payload, and an agent's shell harness commonly truncates long stdout — so the
+// agent silently misses annotations past the cut. We write the FULL result to a
+// sidecar file and surface its path FIRST (`resultFile`), so even a truncated
+// stdout shows where the complete payload is; the agent reads that file with its
+// file tool. Falls back to a plain print if the sidecar can't be written.
+function printResult(result) {
+  const resultFile = result && result.boardId ? saveResultFile(result.boardId, result) : null;
+  printJson(resultFile ? { resultFile, ...result } : result);
+}
+
 // Push-wake for `rly wait --notify-cmd`: run the agent's local shell command
 // once a TERMINAL result lands. Result JSON goes to the command's stdin;
 // RLY_BOARD_ID / RLY_STATUS / RLY_URL are exported. Same shape as the server's
@@ -225,7 +237,7 @@ async function runOrDetach(record, args) {
 
   const { done } = await runBoard({ id: record.id, port, open, timeoutSec });
   const result = await done;
-  printJson(result);
+  printResult(result);
   return exitCodeFor(result.status);
 }
 
@@ -490,7 +502,7 @@ async function cmdWait(args) {
   // Push-wake: run the agent's --notify-cmd after a TERMINAL result, then print.
   const finishResult = (result) => {
     if (notifyCmd) runNotifyCmd(notifyCmd, result);
-    printJson(result);
+    printResult(result);
     return exitCodeFor(result.status);
   };
 
@@ -506,7 +518,7 @@ async function cmdWait(args) {
       if (again?.result?.finishedAt) {
         return finishResult(again.result);
       }
-      printJson({
+      printResult({
         status: 'lost',
         boardId: id,
         draft: again?.draft ?? null,
@@ -552,7 +564,7 @@ async function cmdWaitLoop(id, deadline, opts) {
   const { whileActive, idleGrace, notifyCmd } = opts;
   const finishResult = (result) => {
     if (notifyCmd) runNotifyCmd(notifyCmd, result);
-    printJson(result);
+    printResult(result);
     return exitCodeFor(result.status);
   };
   while (Date.now() < deadline) {
@@ -567,7 +579,7 @@ async function cmdWaitLoop(id, deadline, opts) {
       if (again?.result?.finishedAt) {
         return finishResult(again.result);
       }
-      printJson({
+      printResult({
         status: 'lost',
         boardId: id,
         draft: again?.draft ?? null,
@@ -603,7 +615,7 @@ async function cmdWaitLoop(id, deadline, opts) {
 async function cmdResult(args) {
   const record = mustLoad(args._[0]);
   if (record.result && record.result.finishedAt) {
-    printJson(record.result);
+    printResult(record.result);
     return exitCodeFor(record.result.status);
   }
   const running = loadRunning(record.id);
@@ -613,10 +625,10 @@ async function cmdResult(args) {
     const out = { status: 'open', boardId: record.id, url: running.url, draft: record.draft ?? null };
     const presence = await fetchPresence(running.url);
     if (presence) out.presence = presence;
-    printJson(out);
+    printResult(out); // draft can hold many annotations — sidecar it too
     return 0;
   }
-  printJson({ status: 'lost', boardId: record.id, draft: record.draft ?? null });
+  printResult({ status: 'lost', boardId: record.id, draft: record.draft ?? null });
   return 5;
 }
 
@@ -1380,6 +1392,8 @@ USAGE
                                       --while-active [--idle-grace 180]: keep waiting past the deadline
                                         while the user is still viewing/focused & recently active
                                       --notify-cmd "<cmd>": run <cmd> on a terminal result (JSON on stdin)
+                                      NB: also writes the FULL result to "resultFile" (first field) —
+                                        read that file if your shell truncates stdout; never pipe to head/tail
   rly result <id>                     result/status now (includes live autosaved draft + presence while open)
   rly list [--json]                   running boards
   rly open [id]                       re-open the browser tab of a running board

package/src/store.js

@@ -53,9 +53,25 @@ export function loadBoard(id) {
   }
 }
 
+// Write the full result to its own file (just the result, not the whole board
+// record with its bulky spec). An agent's shell may truncate `rly wait`/`result`
+// stdout for a board with many annotations — this file is the complete payload
+// it can read with a file tool instead. Returns the path (null on failure).
+export function saveResultFile(id, result) {
+  try {
+    ensureDirs();
+    const p = path.join(BOARDS_DIR, `${id}.result.json`);
+    fs.writeFileSync(p, JSON.stringify(result, null, 2));
+    return p;
+  } catch {
+    return null;
+  }
+}
+
 export function deleteBoard(id) {
   try {
     fs.unlinkSync(boardPath(id));
+    try { fs.unlinkSync(path.join(BOARDS_DIR, `${id}.result.json`)); } catch { /* no sidecar */ }
     return true;
   } catch {
     return false;
@@ -66,7 +82,7 @@ export function listBoards(limit = 20) {
   ensureDirs();
   const records = [];
   for (const f of fs.readdirSync(BOARDS_DIR)) {
-    if (!f.endsWith('.json')) continue;
+    if (!f.endsWith('.json') || f.endsWith('.result.json')) continue; // skip result sidecars
     try {
       records.push(JSON.parse(fs.readFileSync(path.join(BOARDS_DIR, f), 'utf8')));
     } catch {