@ai-setting/roy-plugin-task-show 0.4.0 → 0.5.1

package/dist/server.d.ts

@@ -7,16 +7,20 @@
  *   GET /task/:taskId           → detail page (mermaid flow + tables)
  *   GET /api/sessions           → JSON list of sessions
  *   GET /api/sessions/:taskId   → JSON detail of one session
+ *   GET /api/events             → Server-Sent Events stream (real-time push)
  *   GET /static/*               → static frontend assets (CSS/JS)
  *
  * The server is started/stopped via `TaskShowServer.start()` /
- * `.stop()`. Multiple instances cooperate by random port fallback — if the
- * configured port is busy we let the OS pick a free one and log the actual
- * port.
+ * `.stop()`. When the configured port is busy we probe `port + 1`,
+ * `port + 2`, ... in ascending order until a free TCP port is found —
+ * never falling back to an OS-assigned ephemeral port (`listen(0)`).
+ * That keeps the bound port predictable for documentation, fire-and-forget
+ * scripts and ad-hoc coordination between processes.
  */
 import * as http from "node:http";
 import type { TaskShowConfig } from "./types.js";
 import type { ToolCallCollector } from "./collector.js";
+import type { EventBus } from "./event-bus.js";
 /** Public-facing server info (returned to whoever called `start`). */
 export interface ServerInfo {
     host: string;
@@ -26,15 +30,57 @@ export interface ServerInfo {
     /** True if the original port was busy and we had to pick a free one. */
     portRewritten: boolean;
 }
+/** Upper bound of the TCP user port range. Probing never wraps past this. */
+export declare const MAX_TCP_PORT = 65535;
+/** Smallest legal TCP user port (avoid binding to well-known 0..1023). */
+export declare const MIN_TCP_PORT = 1024;
+/** Minimal logger interface used by `listenWithProbing`. */
+export type PortProbingLogger = {
+    info: (m: string) => void;
+    warn: (m: string) => void;
+    error: (m: string) => void;
+};
+/** Outcome of `listenWithProbing`. */
+export interface PortProbingResult {
+    /** The port that was actually bound. */
+    port: number;
+    /** `true` iff we ended up on a port other than the requested start. */
+    portRewritten: boolean;
+}
+/**
+ * Try `server.listen(port, host, …)` starting at `startPort`. If the OS
+ * reports `EADDRINUSE`, increment the port and retry. Stops at 65535 —
+ * never wraps, never falls back to an OS-assigned ephemeral port.
+ *
+ * Only `EADDRINUSE` is retried. Any other listen error (e.g. `EACCES`,
+ * `ENOTSUP`) is surfaced as a normal rejection — the caller is
+ * responsible for closing the server in that case (this helper does
+ * not own the server's lifecycle).
+ *
+ * Listener hygiene: each attempt attaches a fresh one-shot `error`
+ * listener and detaches it as soon as we move on (success, permanent
+ * failure, or exhaustion). This guarantees no duplicate resolve /
+ * reject calls and no listener leaks even when the helper is called
+ * many times on the same server.
+ */
+export declare function listenWithProbing(args: {
+    server: http.Server;
+    host: string;
+    startPort: number;
+    logger?: PortProbingLogger;
+}): Promise<PortProbingResult>;
 export declare class TaskShowServer {
     private server;
     private readonly cfg;
     private readonly collector;
+    private readonly eventBus;
     private readonly publicRoot;
     private readonly logger;
     constructor(opts: {
         cfg: TaskShowConfig;
         collector: ToolCallCollector;
+        /** EventBus for SSE broadcasts. Defaults to a new EventBus if omitted. */
+        eventBus?: EventBus;
         /** Absolute or relative path to the directory with public/index.html. */
         publicDir?: string;
         logger?: {
@@ -44,9 +90,19 @@ export declare class TaskShowServer {
         };
         metaUrl?: string;
     });
+    /**
+     * Get the SSE event bus (for tests / health checks).
+     */
+    getEventBus(): EventBus;
     /**
      * Start the listener. The promise resolves once the server is bound — but
      * the caller can race against `getInfo()` immediately afterwards.
+     *
+     * Port handling: we attempt to bind on `cfg.port` first; if the OS reports
+     * `EADDRINUSE` we probe `cfg.port + 1`, `cfg.port + 2`, ... in ascending
+     * order until a free port is found. The probing never wraps past 65535
+     * and never falls back to `listen(0)`. `ServerInfo.portRewritten` is
+     * `true` whenever the bound port differs from `cfg.port`.
      */
     start(): Promise<ServerInfo>;
     /**
@@ -63,6 +119,13 @@ export declare class TaskShowServer {
      */
     stop(): Promise<void>;
     private handle;
+    /**
+     * SSE handler — sets the SSE headers, sends an initial snapshot, and
+     * subscribes the response to the event bus. The bus will write frames
+     * until the socket closes; the `res.on("close", ...)` listener removes
+     * the subscriber.
+     */
+    private handleSSE;
     /**
      * Render the index page (lists known tasks).
      */

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,KAAK,EAEV,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAMxD,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,wEAAwE;IACxE,aAAa,EAAE,OAAO,CAAC;CACxB;AAcD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuF;gBAElG,IAAI,EAAE;QAChB,GAAG,EAAE,cAAc,CAAC;QACpB,SAAS,EAAE,iBAAiB,CAAC;QAC7B,yEAAyE;QACzE,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE;YAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;YAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;YAAC,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;SAAE,CAAC;QAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;IAOD;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IA0D5B;;;OAGG;IACH,OAAO,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAW7D;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAyBP,MAAM;IAuEpB;;OAEG;IACH,OAAO,CAAC,SAAS;IAKjB;;OAEG;IACH,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,WAAW;IAuBnB,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,QAAQ;CAMjB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -7,18 +7,156 @@
  *   GET /task/:taskId           → detail page (mermaid flow + tables)
  *   GET /api/sessions           → JSON list of sessions
  *   GET /api/sessions/:taskId   → JSON detail of one session
+ *   GET /api/events             → Server-Sent Events stream (real-time push)
  *   GET /static/*               → static frontend assets (CSS/JS)
  *
  * The server is started/stopped via `TaskShowServer.start()` /
- * `.stop()`. Multiple instances cooperate by random port fallback — if the
- * configured port is busy we let the OS pick a free one and log the actual
- * port.
+ * `.stop()`. When the configured port is busy we probe `port + 1`,
+ * `port + 2`, ... in ascending order until a free TCP port is found —
+ * never falling back to an OS-assigned ephemeral port (`listen(0)`).
+ * That keeps the bound port predictable for documentation, fire-and-forget
+ * scripts and ad-hoc coordination between processes.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as http from "node:http";
 import { fileURLToPath } from "node:url";
+import { EventBus as DefaultEventBus, writeSSEHeaders } from "./event-bus.js";
+/** Upper bound of the TCP user port range. Probing never wraps past this. */
+export const MAX_TCP_PORT = 65535;
+/** Smallest legal TCP user port (avoid binding to well-known 0..1023). */
+export const MIN_TCP_PORT = 1024;
 const PUBLIC_DIR = "public";
+// ============================================================================
+// listenWithProbing — sequential port probing helper
+// ============================================================================
+/**
+ * Try `server.listen(port, host, …)` starting at `startPort`. If the OS
+ * reports `EADDRINUSE`, increment the port and retry. Stops at 65535 —
+ * never wraps, never falls back to an OS-assigned ephemeral port.
+ *
+ * Only `EADDRINUSE` is retried. Any other listen error (e.g. `EACCES`,
+ * `ENOTSUP`) is surfaced as a normal rejection — the caller is
+ * responsible for closing the server in that case (this helper does
+ * not own the server's lifecycle).
+ *
+ * Listener hygiene: each attempt attaches a fresh one-shot `error`
+ * listener and detaches it as soon as we move on (success, permanent
+ * failure, or exhaustion). This guarantees no duplicate resolve /
+ * reject calls and no listener leaks even when the helper is called
+ * many times on the same server.
+ */
+export function listenWithProbing(args) {
+    const { server, host, startPort } = args;
+    const logger = args.logger ?? console;
+    // Port 0 is a special sentinel: the caller is asking the OS to assign
+    // an ephemeral port. Honor that directly — no probing needed, no
+    // portRewritten. Any other value must be a valid user-config port.
+    if (startPort === 0) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const onError = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(err);
+            };
+            server.once("error", onError);
+            server.listen(0, host, () => {
+                if (settled)
+                    return;
+                server.removeListener("error", onError);
+                settled = true;
+                const addr = server.address();
+                if (typeof addr === "string" || addr === null) {
+                    reject(new Error("Failed to determine assigned port after listen(0)"));
+                    return;
+                }
+                resolve({ port: addr.port, portRewritten: false });
+            });
+        });
+    }
+    // Reject impossible start ports up-front — no need to touch the
+    // server at all. Saves a confusing EADDRINUSE loop when someone
+    // passes 70000.
+    if (!Number.isInteger(startPort) ||
+        startPort < MIN_TCP_PORT ||
+        startPort > MAX_TCP_PORT) {
+        return Promise.reject(new Error(`Invalid startPort ${startPort}: must be 0 (OS-assigned) or an integer in [${MIN_TCP_PORT}, ${MAX_TCP_PORT}]`));
+    }
+    return new Promise((resolve, reject) => {
+        let port = startPort;
+        let settled = false;
+        // Per-attempt error listener — we explicitly removeListener it before
+        // attaching a new one, so no listeners accumulate across attempts.
+        let onError = null;
+        const finishError = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (onError) {
+                server.removeListener("error", onError);
+                onError = null;
+            }
+            reject(err);
+        };
+        const finishSuccess = (boundPort) => {
+            if (settled)
+                return;
+            settled = true;
+            if (onError) {
+                server.removeListener("error", onError);
+                onError = null;
+            }
+            resolve({
+                port: boundPort,
+                portRewritten: boundPort !== startPort,
+            });
+        };
+        const tryListen = () => {
+            if (settled)
+                return;
+            if (port > MAX_TCP_PORT) {
+                finishError(Object.assign(new Error(`No free TCP port in [${startPort}, ${MAX_TCP_PORT}]: every port busy (EADDRINUSE)`), { code: "EADDRINUSE" }));
+                return;
+            }
+            onError = (err) => {
+                if (settled)
+                    return;
+                const code = err && err.code;
+                if (code === "EADDRINUSE") {
+                    logger.warn(`Port ${port} busy — trying ${port + 1}`);
+                    // Move on. Detach this listener before the next attempt.
+                    if (onError) {
+                        server.removeListener("error", onError);
+                        onError = null;
+                    }
+                    port += 1;
+                    tryListen();
+                    return;
+                }
+                // Any other error: stop immediately.
+                finishError(err);
+            };
+            server.once("error", onError);
+            server.listen(port, host, () => {
+                if (settled)
+                    return;
+                const addr = server.address();
+                if (typeof addr === "string" || addr === null) {
+                    finishError(new Error("Failed to determine assigned port after listen()"));
+                    return;
+                }
+                // `addr.port` is the authoritative bound port. Use it (rather
+                // than our local `port` counter) so a stub server that emits
+                // 'listening' with a port it picked itself still resolves
+                // truthfully.
+                finishSuccess(addr.port);
+            });
+        };
+        tryListen();
+    });
+}
 /** Cached __dirname equivalent for ESM. */
 function getDirname(metaUrl) {
     if (metaUrl)
@@ -32,69 +170,85 @@ export class TaskShowServer {
     server = null;
     cfg;
     collector;
+    eventBus;
     publicRoot;
     logger;
     constructor(opts) {
         this.cfg = opts.cfg;
         this.collector = opts.collector;
+        this.eventBus = opts.eventBus ?? new DefaultEventBus();
         this.publicRoot = resolvePublicDir(opts.publicDir ?? PUBLIC_DIR, opts.metaUrl);
         this.logger = opts.logger ?? console;
     }
+    /**
+     * Get the SSE event bus (for tests / health checks).
+     */
+    getEventBus() {
+        return this.eventBus;
+    }
     /**
      * Start the listener. The promise resolves once the server is bound — but
      * the caller can race against `getInfo()` immediately afterwards.
+     *
+     * Port handling: we attempt to bind on `cfg.port` first; if the OS reports
+     * `EADDRINUSE` we probe `cfg.port + 1`, `cfg.port + 2`, ... in ascending
+     * order until a free port is found. The probing never wraps past 65535
+     * and never falls back to `listen(0)`. `ServerInfo.portRewritten` is
+     * `true` whenever the bound port differs from `cfg.port`.
      */
     start() {
         if (this.server) {
             throw new Error("TaskShowServer already started");
         }
-        return new Promise((resolve, reject) => {
-            const requestListener = (req, res) => {
-                this.handle(req, res).catch((err) => {
-                    this.logger.error(`Unhandled error in HTTP handler: ${err}`);
-                    try {
-                        res.statusCode = 500;
-                        res.setHeader("Content-Type", "text/plain; charset=utf-8");
-                        res.end("Internal Server Error");
-                    }
-                    catch {
-                        // ignore — socket may already be closed
-                    }
-                });
-            };
-            const desiredPort = this.cfg.port;
-            const server = http.createServer(requestListener);
-            server.on("error", (err) => {
-                if (err.code === "EADDRINUSE") {
-                    this.logger.warn(`Port ${desiredPort} busy — falling back to an ephemeral port`);
-                    // Retry on an OS-assigned port.
-                    server.listen(0, this.cfg.host, () => {
-                        const addr = server.address();
-                        if (typeof addr === "string" || addr === null) {
-                            reject(new Error("Failed to determine assigned port"));
-                            return;
-                        }
-                        finish(server, addr.port, true);
-                    });
-                }
-                else {
-                    reject(err);
+        const requestListener = (req, res) => {
+            this.handle(req, res).catch((err) => {
+                this.logger.error(`Unhandled error in HTTP handler: ${err}`);
+                try {
+                    res.statusCode = 500;
+                    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+                    res.end("Internal Server Error");
                 }
-            });
-            server.listen(desiredPort, this.cfg.host, () => {
-                const addr = server.address();
-                if (typeof addr === "string" || addr === null) {
-                    reject(new Error("Failed to determine assigned port"));
-                    return;
+                catch {
+                    // ignore — socket may already be closed
                 }
-                finish(server, addr.port, false);
             });
-            const finish = (srv, port, portRewritten) => {
-                this.server = srv;
-                const url = `http://${this.cfg.host === "0.0.0.0" ? "localhost" : this.cfg.host}:${port}/`;
-                this.logger.info(`HTTP service listening on ${url}`);
-                resolve({ host: this.cfg.host, port, url, server: srv, portRewritten });
+        };
+        const desiredPort = this.cfg.port;
+        const server = http.createServer(requestListener);
+        return listenWithProbing({
+            server,
+            host: this.cfg.host,
+            startPort: desiredPort,
+            logger: this.logger,
+        }).then((probe) => {
+            // success path
+            this.server = server;
+            const url = `http://${this.cfg.host === "0.0.0.0" ? "localhost" : this.cfg.host}:${probe.port}/`;
+            this.logger.info(`HTTP service listening on ${url}` +
+                (probe.portRewritten
+                    ? ` (port rewritten from ${desiredPort} due to conflict)`
+                    : ""));
+            const info = {
+                host: this.cfg.host,
+                port: probe.port,
+                url,
+                server,
+                portRewritten: probe.portRewritten,
             };
+            return info;
+        }, (err) => {
+            // Probing gave up (port range exhausted or a non-EADDRINUSE error
+            // bubbled up). Make sure we close the server we just created so we
+            // don't leak the http.Server handle.
+            try {
+                server.close(() => {
+                    /* swallow — best effort */
+                });
+            }
+            catch {
+                /* ignore */
+            }
+            throw err;
         });
     }
     /**
@@ -124,6 +278,8 @@ export class TaskShowServer {
             }
             const s = this.server;
             this.server = null;
+            // Force-close all SSE clients so the heartbeat loop can exit.
+            this.eventBus.closeAll();
             s.close(() => resolve());
             // Best-effort: tell outstanding sockets to close.
             try {
@@ -148,6 +304,11 @@ export class TaskShowServer {
             return;
         }
         const pathname = url.pathname;
+        // /api/events — SSE stream
+        if (pathname === "/api/events") {
+            this.handleSSE(req, res);
+            return;
+        }
         // /api/sessions
         if (pathname === "/api/sessions") {
             this.json(res, 200, this.collector.listSessions());
@@ -199,6 +360,35 @@ export class TaskShowServer {
         }
         this.text(res, 404, "Not Found");
     }
+    /**
+     * SSE handler — sets the SSE headers, sends an initial snapshot, and
+     * subscribes the response to the event bus. The bus will write frames
+     * until the socket closes; the `res.on("close", ...)` listener removes
+     * the subscriber.
+     */
+    handleSSE(_req, res) {
+        writeSSEHeaders(res);
+        // 1. Send an initial snapshot so the frontend can render immediately.
+        const sessions = this.collector.listSessions();
+        const hello = {
+            type: "snapshot",
+            taskId: 0,
+            timestamp: Date.now(),
+            pluginVersion: "0.5.1",
+            data: { sessions },
+        };
+        try {
+            res.write(`event: snapshot\ndata: ${JSON.stringify(hello)}\n\n`);
+        }
+        catch {
+            // socket may already be closed
+            return;
+        }
+        // 2. Subscribe to the event bus. The bus handles keep-alive pings and
+        //    auto-removal on socket close.
+        this.eventBus.subscribe(res, "sse");
+        this.logger.info(`SSE client connected (total: ${this.eventBus.size()})`);
+    }
     /**
      * Render the index page (lists known tasks).
      */
@@ -302,89 +492,79 @@ function redactArgs(args) {
  */
 function renderTaskPage(session) {
     const statusBadge = session.status;
-    const totalDuration = session.toolCalls.reduce((acc, c) => acc + c.durationMs, 0);
-    const toolStats = aggregateStats(session.toolCalls);
+    const totalMs = session.toolCalls.reduce((a, c) => a + c.durationMs, 0);
+    const successCount = session.toolCalls.filter((c) => c.success).length;
+    const failCount = session.toolCalls.length - successCount;
+    const aggregate = aggregateStats(session.toolCalls);
+    const statsRows = Object.entries(aggregate)
+        .sort((a, b) => b[1].count - a[1].count)
+        .map(([tool, s]) => `<tr><td><code>${htmlEscape(tool)}</code></td>` +
+        `<td>${s.count}</td><td>${s.success}</td><td>${s.fail}</td><td>${s.totalMs} ms</td></tr>`)
+        .join("");
+    const toolcallsTable = renderToolcallsTable(session.toolCalls);
     const mermaid = buildMermaidDiagram(session);
-    const table = renderToolCallsTable(session);
-    const prettyArgs = renderPrettyJson(redactSessionArgs(session.toolCalls));
     return /* html */ `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
-  <title>Task #${session.taskId} — visualization</title>
+  <title>Task #${session.taskId} — roy-plugin-task-show</title>
   <link rel="stylesheet" href="/static/style.css">
   <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
 </head>
-<body>
+<body data-live-refresh data-task-id="${session.taskId}" data-status="${statusBadge}">
   <header class="topbar">
-    <a href="/" class="back">← All tasks</a>
-    <h1>Task #${session.taskId} <span class="badge badge-${statusBadge}">${htmlEscape(statusBadge)}</span></h1>
+    <a class="back" href="/">← All tasks</a>
+    <h1>📊 Task #${session.taskId}</h1>
+    <p class="task-title">${htmlEscape(session.title || "(no title)")}</p>
     <p class="meta">
-      Started: ${htmlEscape(fmtTs(session.startedAt))}
-      ${session.endedAt ? ` · Ended: ${htmlEscape(fmtTs(session.endedAt))}` : " · still running"}
-      · ${session.toolCalls.length} tool calls · total ~${totalDuration} ms
+      <span class="badge badge-${statusBadge}">${statusBadge}</span>
+      · ${session.toolCalls.length} tool call(s)
+      · ${totalMs} ms total
+      · ${successCount} ok / ${failCount} fail
+      · started ${htmlEscape(fmtTs(session.startedAt))}
+      ${session.endedAt ? `· ended ${htmlEscape(fmtTs(session.endedAt))}` : ""}
     </p>
-    ${session.title ? `<p class="task-title">${htmlEscape(session.title)}</p>` : ""}
   </header>
 
   <section class="panel">
-    <h2>📈 Tool frequency</h2>
-    <table class="stats">
-      <thead><tr><th>Tool</th><th>Calls</th><th>Success</th><th>Fail</th><th>Total ms</th><th>Avg ms</th></tr></thead>
-      <tbody>
-        ${Object.entries(toolStats).map(([name, s]) => `
-          <tr>
-            <td><code>${htmlEscape(name)}</code></td>
-            <td>${s.count}</td>
-            <td>${s.success}</td>
-            <td>${s.fail}</td>
-            <td>${s.totalMs}</td>
-            <td>${s.count ? Math.round(s.totalMs / s.count) : 0}</td>
-          </tr>`).join("")}
-      </tbody>
-    </table>
+    <h2>Execution flow (Mermaid)</h2>
+    <div class="mermaid">${mermaid}</div>
   </section>
 
   <section class="panel">
-    <h2>🧭 Tool call flow (mermaid)</h2>
-    <div class="mermaid" id="mermaid">
-${mermaid}
-    </div>
-    <p class="hint">Hover a node to inspect the parameters/result preview. Click to expand the JSON.</p>
+    <h2>Tool call stats</h2>
+    <table class="stats">
+      <thead><tr><th>Tool</th><th>Calls</th><th>OK</th><th>Fail</th><th>Total ms</th></tr></thead>
+      <tbody>${statsRows || `<tr><td colspan="5" class="empty">No tool calls recorded.</td></tr>`}</tbody>
+    </table>
   </section>
 
   <section class="panel">
-    <h2>📜 Tool calls (chronological)</h2>
-    ${table}
+    <h2>Tool calls</h2>
+    ${toolcallsTable}
   </section>
 
   <section class="panel">
-    <h2>🔍 Full payload (JSON)</h2>
+    <h2>Raw JSON</h2>
     <details>
-      <summary>Show / hide raw arguments & output previews</summary>
-      <pre class="json">${htmlEscape(prettyArgs)}</pre>
+      <summary>Click to expand the raw session payload</summary>
+      <pre class="json">${htmlEscape(JSON.stringify(session, null, 2))}</pre>
     </details>
   </section>
 
+  <script src="/static/app.js"></script>
   <script>
-    // Mermaid boot
-    document.addEventListener('DOMContentLoaded', function() {
-      if (window.mermaid) {
-        window.mermaid.initialize({ startOnLoad: true, securityLevel: 'loose', theme: 'default' });
-      }
-    });
+    if (window.mermaid) {
+      window.mermaid.initialize({ startOnLoad: true, theme: 'default', securityLevel: 'loose' });
+    }
   </script>
-  <script src="/static/app.js"></script>
 </body>
 </html>`;
 }
-function renderToolCallsTable(session) {
-    if (session.toolCalls.length === 0) {
-        return `<p class="empty">No tool calls have been recorded yet for this task.</p>`;
-    }
-    const rows = session.toolCalls
+function renderToolcallsTable(toolCalls) {
+    const rows = toolCalls
         .map((call) => {
-        const argsJson = JSON.stringify(redactArgs(call.args)).slice(0, 240);
+        const argsJson = JSON.stringify(redactArgs(call.args));
         const preview = call.error
             ? (call.error.slice(0, 200) + (call.error.length > 200 ? "…" : ""))
             : (call.outputPreview.slice(0, 240) + (call.outputPreview.length > 240 ? "…" : ""));
@@ -436,11 +616,19 @@ function renderIndexPage(sessions) {
   <meta charset="utf-8">
   <title>roy-plugin-task-show · index</title>
   <link rel="stylesheet" href="/static/style.css">
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
 </head>
-<body>
+<body data-live-refresh>
   <header class="topbar">
     <h1>📊 roy-plugin-task-show</h1>
-    <p class="meta">${sessions.length} task session(s) collected this run</p>
+    <p class="meta">
+      ${sessions.length} task session(s) collected this run.
+      Live updates stream over <code>/api/events</code> (SSE).
+    </p>
+    <p class="meta connection-status" data-connection>
+      <span class="conn-dot conn-disconnected"></span>
+      <span class="conn-label">Connecting…</span>
+    </p>
   </header>
   <section class="panel">
     <table class="sessions">
@@ -454,10 +642,17 @@ function renderIndexPage(sessions) {
     <h2>How to read this page</h2>
     <ul>
       <li>Click a task ID to open the mermaid flow + tool call table for that task.</li>
-      <li>The plugin appends a 🔗 URL to the <strong>last</strong> tool result when the task transitions to <code>completed</code> / <code>failed</code>.</li>
+      <li>The page subscribes to <code>GET /api/events</code> for real-time updates (created / recorded / completed).</li>
+      <li>A 3-second polling fallback keeps the page fresh if SSE is blocked (e.g. behind certain proxies).</li>
       <li>Sessions are kept in memory only. Restart the host process to clear all data.</li>
     </ul>
   </section>
+  <script src="/static/app.js"></script>
+  <script>
+    if (window.mermaid) {
+      window.mermaid.initialize({ startOnLoad: true, theme: 'default', securityLevel: 'loose' });
+    }
+  </script>
 </body>
 </html>`;
 }