@ai-setting/roy-plugin-task-show 0.3.0 → 0.5.0

package/dist/event-bus.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Server-Sent Events (SSE) event bus.
+ *
+ * The bus maintains a Set of connected SSE clients (each is an
+ * `http.ServerResponse` already configured for SSE). When the plugin
+ * records a tool call or a task status change, it calls
+ * `eventBus.broadcast(event)` and every connected client receives a
+ * standard SSE `data:` frame.
+ *
+ * The bus also handles client disconnect cleanup and periodic keep-alive
+ * pings (so reverse proxies / load balancers don't drop the connection).
+ *
+ * The implementation is intentionally tiny — no external dependencies, no
+ * abstractions beyond what the plugin needs. Each subscriber is identified
+ * only by a numeric id (assigned on `subscribe`) so `unsubscribe` is
+ * idempotent and safe to call multiple times.
+ */
+import type * as http from "node:http";
+import type { TaskEvent } from "./types.js";
+import { SSE_HEARTBEAT_INTERVAL_MS as HEARTBEAT_MS } from "./types.js";
+/**
+ * Callback invoked by the bus on each broadcast — useful for tests that
+ * don't want to spin up a real HTTP server + EventSource.
+ */
+export type EventListener = (event: TaskEvent) => void;
+/**
+ * Connection handle returned by `subscribe()`. Pass to `unsubscribe()`
+ * when the client disconnects.
+ */
+export interface SubscriberHandle {
+    /** Numeric id assigned at subscribe time. */
+    readonly id: number;
+}
+export declare class EventBus {
+    private clients;
+    private listeners;
+    private nextId;
+    private heartbeatTimer;
+    /**
+     * Register an HTTP response as a new SSE subscriber.
+     *
+     * Caller is responsible for setting up SSE headers on `res` BEFORE
+     * calling this method (use `SSEClient.writeHeaders`). The bus will:
+     *   - register a `close` listener that auto-removes the subscriber
+     *   - start a periodic keep-alive ping (if not already running)
+     *
+     * Returns a handle that can be passed to `unsubscribe()` for explicit
+     * removal (the close listener handles cleanup automatically on socket
+     * close).
+     */
+    subscribe(res: http.ServerResponse, label?: string): SubscriberHandle;
+    /**
+     * Remove a subscriber (idempotent — safe to call multiple times).
+     */
+    unsubscribe(handle: SubscriberHandle): void;
+    /**
+     * Broadcast an event to every connected client and registered listener.
+     *
+     * `event` is serialized with `JSON.stringify` and sent as a single SSE
+     * `data:` frame. Clients with closed sockets are silently dropped from
+     * the subscriber set on the next write attempt.
+     *
+     * Exceptions from individual client writes are caught and logged — one
+     * broken subscriber must not break the rest.
+     */
+    broadcast(event: TaskEvent): void;
+    /**
+     * Register an in-process event listener (test-only path).
+     * Returns a function that unregisters the listener.
+     */
+    addListener(fn: EventListener): () => void;
+    /** Number of currently-connected SSE clients (for tests / health checks). */
+    size(): number;
+    /** True if there are no subscribers. */
+    isEmpty(): boolean;
+    /** Force-close every subscriber (called on dispose). */
+    closeAll(): void;
+    private maybeStartHeartbeat;
+    private maybeStopHeartbeat;
+}
+/**
+ * Format a TaskEvent as an SSE frame. Uses `data: <json>\n\n` per the SSE
+ * spec (https://html.spec.whatwg.org/multipage/server-sent-events.html).
+ *
+ * Optionally a caller can supply an `id:` line so clients can resume from
+ * the last event after a reconnect — currently we omit it (not needed
+ * for the plugin's use case where the frontend re-fetches the full state
+ * snapshot on reconnect).
+ */
+export declare function formatSSEFrame(event: TaskEvent): string;
+/**
+ * Write the standard SSE response headers and the initial comment line.
+ * Helper for `server.ts` to keep the handler readable.
+ */
+export declare function writeSSEHeaders(res: http.ServerResponse): void;
+/** Re-export heartbeat constant for convenience. */
+export { HEARTBEAT_MS };
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,yBAAyB,IAAI,YAAY,EAAE,MAAM,YAAY,CAAC;AAMvE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAyBD,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,cAAc,CAA+C;IAErE;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB;IAoBrE;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAe3C;;;;;;;;;OASG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IA8BjC;;;OAGG;IACH,WAAW,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,IAAI;IAK1C,6EAA6E;IAC7E,IAAI,IAAI,MAAM;IAId,wCAAwC;IACxC,OAAO,IAAI,OAAO;IAIlB,wDAAwD;IACxD,QAAQ,IAAI,IAAI;IAiBhB,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,kBAAkB;CAM3B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAGvD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,GAAG,IAAI,CAW9D;AAED,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/event-bus.js

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Server-Sent Events (SSE) event bus.
+ *
+ * The bus maintains a Set of connected SSE clients (each is an
+ * `http.ServerResponse` already configured for SSE). When the plugin
+ * records a tool call or a task status change, it calls
+ * `eventBus.broadcast(event)` and every connected client receives a
+ * standard SSE `data:` frame.
+ *
+ * The bus also handles client disconnect cleanup and periodic keep-alive
+ * pings (so reverse proxies / load balancers don't drop the connection).
+ *
+ * The implementation is intentionally tiny — no external dependencies, no
+ * abstractions beyond what the plugin needs. Each subscriber is identified
+ * only by a numeric id (assigned on `subscribe`) so `unsubscribe` is
+ * idempotent and safe to call multiple times.
+ */
+import { SSE_HEARTBEAT_INTERVAL_MS as HEARTBEAT_MS } from "./types.js";
+// ============================================================================
+// EventBus
+// ============================================================================
+export class EventBus {
+    clients = new Set();
+    listeners = new Set();
+    nextId = 1;
+    heartbeatTimer = null;
+    /**
+     * Register an HTTP response as a new SSE subscriber.
+     *
+     * Caller is responsible for setting up SSE headers on `res` BEFORE
+     * calling this method (use `SSEClient.writeHeaders`). The bus will:
+     *   - register a `close` listener that auto-removes the subscriber
+     *   - start a periodic keep-alive ping (if not already running)
+     *
+     * Returns a handle that can be passed to `unsubscribe()` for explicit
+     * removal (the close listener handles cleanup automatically on socket
+     * close).
+     */
+    subscribe(res, label) {
+        const id = this.nextId++;
+        const client = {
+            id,
+            res,
+            connectedAt: Date.now(),
+            ...(label !== undefined ? { label } : {}),
+        };
+        this.clients.add(client);
+        // Auto-cleanup on socket close.
+        res.on("close", () => {
+            this.clients.delete(client);
+            this.maybeStopHeartbeat();
+        });
+        this.maybeStartHeartbeat();
+        return { id };
+    }
+    /**
+     * Remove a subscriber (idempotent — safe to call multiple times).
+     */
+    unsubscribe(handle) {
+        for (const c of this.clients) {
+            if (c.id === handle.id) {
+                this.clients.delete(c);
+                try {
+                    c.res.end();
+                }
+                catch {
+                    // socket may already be closed
+                }
+                break;
+            }
+        }
+        this.maybeStopHeartbeat();
+    }
+    /**
+     * Broadcast an event to every connected client and registered listener.
+     *
+     * `event` is serialized with `JSON.stringify` and sent as a single SSE
+     * `data:` frame. Clients with closed sockets are silently dropped from
+     * the subscriber set on the next write attempt.
+     *
+     * Exceptions from individual client writes are caught and logged — one
+     * broken subscriber must not break the rest.
+     */
+    broadcast(event) {
+        const frame = formatSSEFrame(event);
+        // Drop dead clients up front.
+        const dead = [];
+        for (const c of this.clients) {
+            if (c.res.writableEnded || c.res.destroyed) {
+                dead.push(c);
+                continue;
+            }
+            try {
+                c.res.write(frame);
+            }
+            catch {
+                dead.push(c);
+            }
+        }
+        for (const d of dead)
+            this.clients.delete(d);
+        // Listeners (for tests / in-process subscribers).
+        for (const l of this.listeners) {
+            try {
+                l(event);
+            }
+            catch {
+                // Listener errors must not break the broadcast.
+            }
+        }
+        this.maybeStopHeartbeat();
+    }
+    /**
+     * Register an in-process event listener (test-only path).
+     * Returns a function that unregisters the listener.
+     */
+    addListener(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    /** Number of currently-connected SSE clients (for tests / health checks). */
+    size() {
+        return this.clients.size;
+    }
+    /** True if there are no subscribers. */
+    isEmpty() {
+        return this.clients.size === 0;
+    }
+    /** Force-close every subscriber (called on dispose). */
+    closeAll() {
+        for (const c of this.clients) {
+            try {
+                c.res.end();
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.clients.clear();
+        this.listeners.clear();
+        this.maybeStopHeartbeat();
+    }
+    // ---------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------
+    maybeStartHeartbeat() {
+        if (this.heartbeatTimer)
+            return;
+        if (this.clients.size === 0)
+            return;
+        this.heartbeatTimer = setInterval(() => {
+            for (const c of this.clients) {
+                if (c.res.writableEnded || c.res.destroyed)
+                    continue;
+                try {
+                    // SSE comment lines start with `:` and are ignored by EventSource.
+                    c.res.write(":keep-alive\n\n");
+                }
+                catch {
+                    // ignore — next broadcast will reap
+                }
+            }
+        }, HEARTBEAT_MS);
+        // Don't keep the event loop alive just for heartbeats.
+        if (typeof this.heartbeatTimer.unref === "function") {
+            this.heartbeatTimer.unref();
+        }
+    }
+    maybeStopHeartbeat() {
+        if (this.heartbeatTimer && this.clients.size === 0) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Format a TaskEvent as an SSE frame. Uses `data: <json>\n\n` per the SSE
+ * spec (https://html.spec.whatwg.org/multipage/server-sent-events.html).
+ *
+ * Optionally a caller can supply an `id:` line so clients can resume from
+ * the last event after a reconnect — currently we omit it (not needed
+ * for the plugin's use case where the frontend re-fetches the full state
+ * snapshot on reconnect).
+ */
+export function formatSSEFrame(event) {
+    const json = JSON.stringify(event);
+    return `event: ${event.type}\ndata: ${json}\n\n`;
+}
+/**
+ * Write the standard SSE response headers and the initial comment line.
+ * Helper for `server.ts` to keep the handler readable.
+ */
+export function writeSSEHeaders(res) {
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no"); // disable nginx buffering
+    // Some browsers / proxies require a 2KB initial response to flush headers.
+    res.write(":ok\n\n");
+    if (typeof res.flushHeaders === "function") {
+        res.flushHeaders();
+    }
+}
+/** Re-export heartbeat constant for convenience. */
+export { HEARTBEAT_MS };
+//# sourceMappingURL=event-bus.js.map

package/dist/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -9,12 +9,13 @@
 export { TaskShowPlugin, createTaskShowPlugin, } from "./plugin.js";
 export type { TaskShowPluginInterface } from "./plugin.js";
 export { DEFAULT_CONFIG, } from "./types.js";
-export type { TaskShowConfig, PluginEnvLike, TaskSession, ToolCallRecord, } from "./types.js";
+export type { TaskShowConfig, PluginEnvLike, TaskSession, ToolCallRecord, TaskEvent, TaskEventType, TaskCreatedEventData, TaskUpdatedEventData, TaskCompletedEventData, ToolRecordedEventData, TypedTaskEvent, } from "./types.js";
 export { ToolCallCollector, } from "./collector.js";
 export { TaskShowServer, } from "./server.js";
 export type { ServerInfo } from "./server.js";
-export { buildVisualizationUrl, buildIndexUrl, injectVisualizationUrl, appendVisualizationBanner, } from "./url-injector.js";
-export type { InjectionResult } from "./url-injector.js";
+export { EventBus, formatSSEFrame, writeSSEHeaders, } from "./event-bus.js";
+export type { SubscriberHandle, EventListener } from "./event-bus.js";
+export { buildVisualizationUrl, buildIndexUrl, } from "./url-injector.js";
 import TaskShowPlugin from "./plugin.js";
 export default TaskShowPlugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,cAAc,EACd,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EACL,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,cAAc,MAAM,aAAa,CAAC;AACzC,eAAe,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,cAAc,EACd,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EACL,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EACd,SAAS,EACT,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EACL,QAAQ,EACR,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEtE,OAAO,EACL,qBAAqB,EACrB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,cAAc,MAAM,aAAa,CAAC;AACzC,eAAe,cAAc,CAAC"}

package/dist/index.js

@@ -10,7 +10,8 @@ export { TaskShowPlugin, createTaskShowPlugin, } from "./plugin.js";
 export { DEFAULT_CONFIG, } from "./types.js";
 export { ToolCallCollector, } from "./collector.js";
 export { TaskShowServer, } from "./server.js";
-export { buildVisualizationUrl, buildIndexUrl, injectVisualizationUrl, appendVisualizationBanner, } from "./url-injector.js";
+export { EventBus, formatSSEFrame, writeSSEHeaders, } from "./event-bus.js";
+export { buildVisualizationUrl, buildIndexUrl, } from "./url-injector.js";
 import TaskShowPlugin from "./plugin.js";
 export default TaskShowPlugin;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,cAAc,EACd,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,cAAc,GACf,MAAM,YAAY,CAAC;AAQpB,OAAO,EACL,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,cAAc,MAAM,aAAa,CAAC;AACzC,eAAe,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,cAAc,EACd,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,cAAc,GACf,MAAM,YAAY,CAAC;AAepB,OAAO,EACL,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,QAAQ,EACR,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,qBAAqB,EACrB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,cAAc,MAAM,aAAa,CAAC;AACzC,eAAe,cAAc,CAAC"}

package/dist/plugin.d.ts

@@ -4,16 +4,37 @@
  * Lifecycle (mirrors `ReminderPlugin` / `TaskTagPlugin`):
  *   1. Constructor accepts a config (defaults merged in).
  *   2. `init(env)` registers hooks on the global hook manager:
- *        - `tool:after.execute`           → record each tool call
- *        - `task:after.update`            → freeze session + emit URL
+ *        - `tool:before.execute`           → record per-call start timestamp
+ *        - `tool:after.execute`            → record each tool call
+ *        - `task:before.create`            → open a new TaskSession
+ *        - `task:after.create`             → mark session ready
+ *        - `task:after.update`             → freeze + broadcast status update
+ *        - `task:after.complete`           → freeze + broadcast terminal status
  *   3. `dispose()` stops the HTTP service & releases listeners.
  *
  * The plugin is intentionally lean: all the heavy lifting lives in
- * `collector.ts`, `server.ts`, and `url-injector.ts`. That keeps this file
+ * `collector.ts`, `server.ts`, and `event-bus.ts`. That keeps this file
  * readable and makes the surface area easy to test.
+ *
+ * ## Visualization reach-out (v0.5.0+)
+ *
+ * v0.5.0 replaces the previous `env.notify({type:"visualization_ready"})`
+ * mechanism with a Server-Sent Events stream served by the local HTTP
+ * service. The frontend subscribes to `GET /api/events` and receives a
+ * real-time push every time:
+ *
+ *   - a new task is created (`task.created`)
+ *   - a tool call is recorded (`tool.recorded`)
+ *   - a task status changes (`task.updated`)
+ *   - a task transitions to terminal status (`task.completed`)
+ *
+ * This eliminates the host-side NotificationChannel plumbing and works
+ * with any roy-agent host — including ones that pre-date the
+ * NotificationChannel abstraction.
  */
 import type { PluginEnvLike, TaskShowConfig } from "./types.js";
 import { ToolCallCollector } from "./collector.js";
+import { EventBus } from "./event-bus.js";
 /**
  * Public, friendly type used in README + tests.
  *
@@ -31,8 +52,15 @@ export interface TaskShowPluginInterface {
     getServerPort(): number | null;
     /** accessor for tests / health checks */
     getCollector(): ToolCallCollector;
+    /** accessor for tests / health checks */
+    getEventBus(): EventBus;
     /** accessor for tests that want to bypass the hook manager entirely */
     getConfig(): TaskShowConfig;
+    /**
+     * Compute the URL the page would be served at. Helpful in tests where
+     * `init()` was skipped.
+     */
+    getVisualizationUrl(taskId: number): string;
 }
 /**
  * Main plugin class. Decorated with the static `roy-agent` metadata block
@@ -40,15 +68,14 @@ export interface TaskShowPluginInterface {
  */
 export declare class TaskShowPlugin implements TaskShowPluginInterface {
     readonly name = "roy-plugin-task-show";
-    readonly version = "0.1.0";
-    readonly description = "Visually trace a task's tool-call chain on a local HTTP service and inject the URL into the last tool result.";
+    readonly version = "0.5.0";
+    readonly description = "Visually trace a task's tool-call chain on a local HTTP service. v0.5.0+ uses Server-Sent Events for real-time page updates (no host NotificationChannel required).";
     private readonly cfg;
     private readonly collector;
     private readonly server;
+    private readonly eventBus;
     private env;
     private disposed;
-    /** Last successful `tool:after.execute` result, used to inject the URL on task completion. */
-    private lastResultByTask;
     /**
      * `tool:before.execute` → `tool:after.execute` start-time buffer.
      * Keyed by a fingerprint derived from (taskId, toolName, argsHash) so
@@ -66,8 +93,8 @@ export declare class TaskShowPlugin implements TaskShowPluginInterface {
      * (which can happen on newer hosts where both hook points fire on
      * completion). Cleared on dispose().
      */
-    private injectedTaskIds;
-    /** cached list of hook points we registered, so dispose() can be defensive even if the env lacks unregister. */
+    private finalizedTaskIds;
+    /** Cached list of hook points we registered, so dispose() can be defensive even if the env lacks unregister. */
     private registered;
     constructor(config?: Partial<TaskShowConfig>);
     /**
@@ -82,7 +109,9 @@ export declare class TaskShowPlugin implements TaskShowPluginInterface {
     dispose(): Promise<void>;
     getServerPort(): number | null;
     getCollector(): ToolCallCollector;
+    getEventBus(): EventBus;
     getConfig(): TaskShowConfig;
+    getVisualizationUrl(taskId: number): string;
     /**
      * Public function exposed so unit tests can simulate the
      * `tool:before.execute` payload (without going through the global hook
@@ -100,21 +129,35 @@ export declare class TaskShowPlugin implements TaskShowPluginInterface {
      */
     onToolAfterExecute(ctx: any, metadata?: Record<string, unknown>): Promise<void>;
     /**
-     * Public function exposed for tests; mirrors the `task:after.update`
-     * payload.
+     * Public function exposed for tests; mirrors the `task:before.create`
+     * payload. We use it to mint a fresh TaskSession before any tool call
+     * is recorded (gives us a stable taskId/title even if no tool fires).
      */
+    onTaskBeforeCreate(ctx: any): Promise<void>;
+    /**
+     * Public function exposed for tests; mirrors the `task:after.create`
+     * payload. Right now this is mostly a no-op (session was already opened
+     * in `onTaskBeforeCreate`); the hook is wired so the frontend can
+     * distinguish "task opened" from "task started executing".
+     *
+     * Hosts that only emit `task:after.create` (no before) are also
+     * supported — in that case the session is opened here.
+     */
+    onTaskAfterCreate(ctx: any): Promise<void>;
     /**
      * Public function exposed for tests; mirrors BOTH the preferred
-     * `task:after.complete` payload (added in roy-agent 2026-07-10) AND
-     * the legacy `task:after.update` payload. Both hook points reach this
-     * handler; an internal dedup set guarantees at most one URL injection
-     * per task.
+     * `task:after.complete` payload AND the legacy `task:after.update`
+     * payload.
+     *
+     *  - `task:after.complete` (preferred, terminal):
+     *    - `data.terminalStatus` is explicit; no filtering needed.
+     *  - `task:after.update` (legacy):
+     *    - `data.task.status` carries the new status. We treat it as a
+     *      generic status update — terminal vs non-terminal decides which
+     *      event type we broadcast.
      *
-     *  - Preferred (roy-agent 2026-07-10+): `task:after.complete`
-     *    - `data.terminalStatus` is explicit; no status filtering needed.
-     *  - Legacy fallback (pre-2026-07-10 roy-agent): `task:after.update`
-     *    - only `data.task` is provided; we filter for terminal statuses
-     *      the same way the previous implementation did.
+     * An internal dedup set guarantees that when both hook points fire
+     * (newer hosts), we broadcast the terminal event exactly once.
      */
     onTaskAfterComplete(ctx: any): Promise<void>;
     /**
@@ -124,15 +167,13 @@ export declare class TaskShowPlugin implements TaskShowPluginInterface {
      */
     onTaskAfterUpdate(ctx: any): Promise<void>;
     /**
-     * Manual injection hook — useful when a custom caller has a known task
-     * id + ToolResult at hand (e.g. tests).
-     */
-    injectFor(taskId: number, result: any): boolean;
-    /**
-     * Compute the URL the page would be served at. Helpful in tests where
-     * `init()` was skipped.
+     * Construct a TaskEvent and push it to every connected SSE client.
+     *
+     * The broadcast is fire-and-forget; SSE write failures are absorbed by
+     * the bus itself, so this method never throws. Centralizing the event
+     * construction here keeps every hook handler symmetric.
      */
-    getVisualizationUrl(taskId: number): string;
+    private broadcast;
     /**
      * Subscribe to the hook points we care about. We try to use the env's
      * `registerHook` first (the modern, type-safe plugin API), then fall back

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EAEf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAgCnD;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,yCAAyC;IACzC,aAAa,IAAI,MAAM,GAAG,IAAI,CAAC;IAC/B,yCAAyC;IACzC,YAAY,IAAI,iBAAiB,CAAC;IAClC,uEAAuE;IACvE,SAAS,IAAI,cAAc,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,cAAe,YAAW,uBAAuB;IAC5D,QAAQ,CAAC,IAAI,0BAA0B;IACvC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,WAAW,mHAC8F;IAElH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,GAAG,CAA8B;IACzC,OAAO,CAAC,QAAQ,CAAS;IACzB,8FAA8F;IAC9F,OAAO,CAAC,gBAAgB,CAA0B;IAElD;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa,CAAkC;IAEvD;;;;;OAKG;IACH,OAAO,CAAC,eAAe,CAA0B;IACjD,gHAAgH;IAChH,OAAO,CAAC,UAAU,CAAyC;gBAE/C,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAgB5C;;;;OAIG;IACG,IAAI,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB7C;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB9B,aAAa,IAAI,MAAM,GAAG,IAAI;IAK9B,YAAY,IAAI,iBAAiB;IAIjC,SAAS,IAAI,cAAc;IAQ3B;;;;;;;;OAQG;IACG,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtF;;;;OAIG;IACG,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA0DrF;;;OAGG;IACH;;;;;;;;;;;;OAYG;IACG,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA8DlD;;;;OAIG;IACG,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAGhD;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO;IAU/C;;;OAGG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAQ3C;;;;OAIG;IACH,OAAO,CAAC,aAAa;YAsDP,wBAAwB;IAiDtC;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAoBhC;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,kBAAkB;CAK3B;AA+BD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAErF;AAED;;;GAGG;AACH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}