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

package/README.md

@@ -1,35 +1,41 @@
 # roy-plugin-task-show
 
 > A [roy-agent](https://example/roy-agent) plugin that visualizes the tool-call
-> chain of every task on a local web service and **notifies** the visualization
-> URL through the host's `env.notify` event-bus API.
+> chain of every task on a local web service with **real-time Server-Sent
+> Events** for live page updates.
 
 ## What it does
 
 When loaded into a `roy-agent` host, this plugin:
 
 1. Listens to the `tool:before.execute`, `tool:after.execute`,
-   `task:after.complete` (preferred) and `task:after.update` (legacy fallback)
-   hook points.
+   `task:before.create`, `task:after.create`, `task:after.complete`
+   (preferred) and `task:after.update` (legacy fallback) hook points.
 2. Records every tool invocation (tool name, args, result preview, duration,
    success flag, timestamp) into an in-memory collector keyed by task id.
-3. When a task transitions to a terminal status (`completed` / `failed` /
-   `cancelled` / `timeout`), emits a **`visualization_ready` notification**
-   through `env.notify({ type: "visualization_ready", ... })`. The host's
-   `NotificationChannel` pipeline (default: `EventBusNotificationChannel`)
-   re-emits it on the env event bus as
-   `plugin.notification.visualization_ready`.
+3. **Pushes every state change over a Server-Sent Events stream** served by
+   the plugin's local HTTP service. The frontend subscribes to
+   `GET /api/events` and re-renders the page within milliseconds of:
+   - a new task being created (`task.created`)
+   - a tool call being recorded (`tool.recorded`)
+   - a task status changing (`task.updated`)
+   - a task transitioning to a terminal status (`task.completed`)
 4. Serves the visualization on a local HTTP server (default
-   `http://127.0.0.1:7788/`).
-
-The result: every task in the chat gets a 🔗 link the user can click to open
-a mermaid-powered flow chart showing exactly how the agent solved it. The
-link can be rendered by any subscriber to the env event bus (CLI / IM
-adapter / custom webhook).
-
-> **v0.4.0+** — the plugin no longer mutates tool result output. The
-> visualization reach-out goes through `env.notify` instead. See
-> [env.notify Migration (v0.4.0+)](#envnotify-migration-v040) for the
+   `http://127.0.0.1:7788/`) — index page, per-task detail page, and the
+   `/api/events` SSE stream.
+
+The result: every task gets a clickable link the user can open in a
+browser. Once open, the page **stays in sync** with the running agent
+loop — tool calls appear as they happen, status badges update in
+real-time, and the progress bar grows with each call. No manual refresh
+needed.
+
+> **v0.5.0+** — the plugin no longer uses `env.notify`. The previous
+> `env.notify({type:"visualization_ready"})` mechanism has been replaced
+> with an in-process event bus + SSE stream. This makes the plugin work
+> with **any** roy-agent host (no NotificationChannel required) and gives
+> the frontend proper incremental updates instead of just a one-shot URL
+> at the end. See [SSE Migration (v0.5.0+)](#sse-migration-v050) for the
 > migration guide.
 
 ## Repository layout
@@ -46,17 +52,20 @@ roy-plugin-task-show/
 │   └── app.js
 ├── src/
 │   ├── index.ts             ← public API (re-exports)
-│   ├── types.ts             ← shared types & default config
+│   ├── types.ts             ← shared types & default config + TaskEvent
 │   ├── collector.ts         ← in-memory tool-call collector
-│   ├── server.ts            ← tiny standalone Node http server (no deps)
-│   ├── url-injector.ts      ← tool-result mutation helpers
+│   ├── server.ts            ← tiny standalone Node http server + SSE endpoint
+│   ├── event-bus.ts         ← SSE event bus (broadcast / subscribe / keep-alive)
+│   ├── url-injector.ts      ← URL builders (no more mutation helpers)
 │   ├── plugin.ts            ← the TaskShowPlugin class (BasePlugin-compatible)
 │   └── core-stub.d.ts       ← type stub for the optional core peer dep
 ├── test/
 │   ├── collector.test.ts
 │   ├── url-injector.test.ts
-│   ├── server.test.ts
-│   └── plugin.test.ts
+│   ├── server.test.ts       ← includes SSE endpoint test
+│   ├── plugin.test.ts       ← covers all six hooks + broadcast assertions
+│   ├── plugin-sse.test.ts   ← dedicated SSE event-bus consumer tests
+│   └── integration.test.ts  ← full lifecycle through HTTP + SSE
 └── scripts/
     ├── verify-service.ts    ← end-to-end check (port 7788 + curl pages)
     └── run-demo.ts          ← demo that simulates a real task lifecycle
@@ -134,85 +143,187 @@ await taskShow.dispose();
 
 The plugin registers hooks for:
 
-- `tool:after.execute`     — collects every tool call (priority 50).
-- `task:after.complete`     — PREFERRED — freezes the session and injects
-  the visualization URL on terminal status transition. Available on
-  `roy-agent` versions >= 2026-07-10 (priority 60).
-- `task:after.update`       — LEGACY fallback for hosts predating the new
-  hook point. The handler also dedupes against any `task:after.complete`
-  that fires simultaneously, so on a modern host the URL is injected
-  exactly once (priority 60).
+| Hook point             | Priority | Purpose                                                                  |
+| ---------------------- | -------- | ------------------------------------------------------------------------ |
+| `tool:before.execute`  | 40       | Records per-call start timestamp for accurate `durationMs`              |
+| `tool:after.execute`   | 50       | Records the call into the collector and broadcasts `tool.recorded`       |
+| `task:before.create`   | 55       | Mints a fresh `TaskSession` and broadcasts `task.created`               |
+| `task:after.create`    | 55       | Same as above (fallback for hosts that only emit `task:after.create`)    |
+| `task:after.complete`  | 60       | **PREFERRED** — broadcasts `task.completed` on terminal transition       |
+| `task:after.update`    | 60       | Legacy fallback; broadcasts `task.updated` or `task.completed`           |
+
+When both `task:after.complete` AND `task:after.update` fire (newer
+hosts do this on completion), the handler dedupes — at most one
+`task.completed` event per task.
 
 ## Configuration
 
 All config lives in `plugin.json` (and is overridable at construction time):
 
-| key                 | type     | default     | description                                              |
-| ------------------- | -------- | ----------- | -------------------------------------------------------- |
-| `port`              | number   | `7788`      | HTTP port for the visualization service.                 |
-| `host`              | string   | `127.0.0.1` | HTTP host. Use `0.0.0.0` to allow LAN access.            |
-| `autoStart`         | boolean  | `true`      | Start the HTTP server when `init()` is called.           |
-| `maxStoredTasks`    | number   | `50`        | Max sessions kept in memory. Older ones are evicted.     |
-| `urlInjectEnabled`  | boolean  | `false`     | **DEPRECATED** in v0.4.0. Appends the visualization URL to the last tool result. Defaults to `false` — the plugin reaches out via `env.notify` instead. |
-| `publicDir`         | string   | `public`    | Directory holding the static frontend.                   |
+| key              | type     | default     | description                                              |
+| ---------------- | -------- | ----------- | -------------------------------------------------------- |
+| `port`           | number   | `7788`      | HTTP port for the visualization service.                 |
+| `host`           | string   | `127.0.0.1` | HTTP host. Use `0.0.0.0` to allow LAN access.            |
+| `autoStart`      | boolean  | `true`      | Start the HTTP server when `init()` is called.           |
+| `maxStoredTasks` | number   | `50`        | Max sessions kept in memory. Older ones are evicted.     |
+| `publicDir`      | string   | `public`    | Directory holding the static frontend.                   |
+
+> **v0.5.0**: the previous `urlInjectEnabled` config was removed. The
+> plugin no longer mutates tool result output.
 
 Override at construction time:
 
 ```ts
 createTaskShowPlugin({
   port: 9000,
-  urlInjectEnabled: false,
+  maxStoredTasks: 100,
 });
 ```
 
 ## HTTP API
 
-| route                       | description                                            |
-| --------------------------- | ------------------------------------------------------ |
-| `GET /`                     | Index of recent task sessions.                         |
-| `GET /task/:taskId`         | Per-task page with mermaid flow + tool-call table.     |
-| `GET /api/sessions`         | JSON list of all sessions (newest first).              |
-| `GET /api/sessions/:taskId` | JSON detail of one session (full payload).             |
-| `GET /static/*`             | Static frontend assets (`style.css`, `app.js`).        |
+| route                       | description                                                  |
+| --------------------------- | ------------------------------------------------------------ |
+| `GET /`                     | Index of recent task sessions.                               |
+| `GET /task/:taskId`         | Per-task page with mermaid flow + tool-call table.           |
+| `GET /api/sessions`         | JSON list of all sessions (newest first).                    |
+| `GET /api/sessions/:taskId` | JSON detail of one session (full payload).                   |
+| **`GET /api/events`**       | **SSE stream** — see [Server-Sent Events](#server-sent-events). |
+| `GET /static/*`             | Static frontend assets (`style.css`, `app.js`).              |
 
 If the configured `port` is already in use, the service falls back to an OS
 assigned port and logs the actual URL to stderr.
 
+## Server-Sent Events
+
+The local HTTP service exposes `GET /api/events` as a standard Server-Sent
+Events stream. Every connected client receives:
+
+1. An initial `snapshot` frame carrying the full list of currently-known
+   sessions — useful for instant render on connect / reconnect.
+2. A `task.created` frame whenever a new task is opened
+   (`task:before.create` or `task:after.create`).
+3. A `tool.recorded` frame after each tool call
+   (`tool:after.execute`).
+4. A `task.updated` frame on any non-terminal status transition
+   (`task:after.update` with `running` / `paused` / etc.).
+5. A `task.completed` frame on terminal transition
+   (`task:after.complete` or `task:after.update` with terminal status).
+
+A 15-second keep-alive comment (`:keep-alive`) prevents reverse proxies /
+load balancers from dropping the connection.
+
+### Event shape
+
+Every event has the same envelope:
+
+```ts
+interface TaskEvent<T> {
+  type: "task.created" | "task.updated" | "task.completed" | "tool.recorded";
+  taskId: number;
+  timestamp: number;       // Unix ms
+  pluginVersion: string;   // "0.5.0"
+  data: T;
+}
+```
+
+The `data` payload differs per `type`:
+
+```ts
+// task.created
+data: { session: TaskSession }
+
+// task.updated
+data: { session: TaskSession, newStatus: TaskStatus, previousStatus?: TaskStatus }
+
+// task.completed
+data: { session: TaskSession, terminalStatus: TaskStatus }
+
+// tool.recorded
+data: { session: TaskSession, toolCall: ToolCallRecord }
+```
+
+### Subscribing from the browser
+
+```ts
+const source = new EventSource("/api/events");
+source.addEventListener("snapshot", (ev) => {
+  const data = JSON.parse(ev.data);
+  console.log("initial sessions:", data.data.sessions);
+});
+source.addEventListener("task.created", (ev) => {
+  const data = JSON.parse(ev.data);
+  console.log("new task:", data.data.session.taskId);
+});
+source.addEventListener("tool.recorded", (ev) => {
+  const data = JSON.parse(ev.data);
+  console.log("tool call:", data.data.toolCall.toolName);
+});
+source.addEventListener("task.completed", (ev) => {
+  const data = JSON.parse(ev.data);
+  console.log("task done:", data.data.terminalStatus);
+});
+// EventSource auto-reconnects on connection drop. If SSE is unavailable
+// (e.g. ancient browser), the bundled frontend falls back to a 3-second
+// poll of /api/sessions.
+```
+
+### Subscribing from Node / custom adapter
+
+```ts
+import http from "node:http";
+
+http.get("http://127.0.0.1:7788/api/events", (res) => {
+  let buf = "";
+  res.on("data", (chunk) => {
+    buf += chunk.toString("utf-8");
+    let idx;
+    while ((idx = buf.indexOf("\n\n")) !== -1) {
+      const frame = buf.slice(0, idx);
+      buf = buf.slice(idx + 2);
+      // frame is `event: <type>\ndata: <json>`
+      // ...
+    }
+  });
+});
+```
+
 ## Architecture
 
-The plugin runs as a peer of the host (`roy-agent`) and depends on three
-host-side constructs:
+The plugin runs entirely inside its local HTTP server. The hook handlers
+emit events into an in-process `EventBus` (`src/event-bus.ts`), and every
+connected SSE client receives a frame. No host-side NotificationChannel
+plumbing is required.
 
 ```
-TaskShowPlugin (task:after.complete hook)
+TaskShowPlugin (tool/task hooks)
        │
-       │  env.notify({type: "visualization_ready", title, content, metadata})
+       │  eventBus.broadcast({type, taskId, timestamp, data})
        ▼
-PluginComponent.routeNotification()
+EventBus  (in-process subscriber Set + keep-alive loop)
        │
+       │  write frame to every connected http.ServerResponse
        ▼
-EventBusNotificationChannel  (default)
+TaskShowServer.handleSSE
        │
-       │  env.pushEnvEvent({
-       │     type: "plugin.notification.visualization_ready",
-       │     metadata: { source: "plugin:roy-plugin-task-show", ...pluginMetadata },
-       │     payload: { title, content },
-       │  })
+       │  Content-Type: text/event-stream
        ▼
-Env-level Event Subscriber
+Browser EventSource  ◄──── 3-second polling fallback if SSE unavailable
        │
-       ├──► CLI adapter  → print "📊 Task #X completed: http://..."
-       ├──► IM adapter   → lark-cli / webhook → 飞书消息
-       └──► custom sinks → log, metrics, etc.
+       ▼
+DOM updates (badge / progress / timeline / mermaid re-render)
 ```
 
-The plugin's own notification layer is intentionally minimal: it
-formats the title + content for human display and packages structured
-metadata for subscribers. Delivery, deduplication across subscribers,
-and persistent retry logic all live in the host. This keeps the
-plugin easy to test (we just assert `env.notify` was called with the
-right payload) and lets each deployment pick the IM / CLI front-ends
-that match its audience.
+The in-process bus also exposes `addListener(fn)` so custom callers
+(CLI tools, IM adapters, log shippers) can subscribe to the same event
+stream without going through HTTP:
+
+```ts
+const plugin = createTaskShowPlugin();
+plugin.getEventBus().addListener((event) => {
+  console.log("event:", event.type, event.taskId);
+});
+```
 
 ### Plugin ↔ host version correspondence
 
@@ -221,143 +332,98 @@ that match its audience.
 | `0.1.0`        | pre-2026-07-10 (`task:after.update`) | Mutates tool result. **Removed** in v0.4.0 plugin.                 |
 | `0.2.0`        | pre-2026-07-10 (`task:after.update`) | Same as 0.1.0; tiny refactors.                                     |
 | `0.3.0`        | `>= 2026-07-10`                      | Adds `tool:before.execute` for self-managed timing.                |
-| `0.4.0` (this) | `>= 2026-07-10` (NotificationChannel) | Switches to `env.notify` consumer; no longer mutates output.     |
-
-The host's `PluginEnv.notify` method is **optional** for the plugin — it
-degrades gracefully on older hosts (logs a one-shot warn, continues
-serving the visualization page). The plugin therefore remains
-installable on any host version, but newer features only fire on
-hosts implementing the v0.4.0+ contract.
+| `0.4.0`        | `>= 2026-07-10` (NotificationChannel) | Switches to `env.notify` consumer; no longer mutates output.     |
+| **`0.5.0` (this)** | **`>= 2026-07-10`**             | **Adds `task:before.create` / `task:after.create`; switches from `env.notify` to in-process EventBus + SSE.** |
 
 ### Host design reference
 
 The full host-side design — including the `NotificationChannel`
-interface, `EventBusNotificationChannel` (default) and
-`LarkCliNotificationChannel` (legacy, `@deprecated`) — is documented
+interface and `EventBusNotificationChannel` (default) — is documented
 in the host repository:
 
-> **`roy-agent/docs/plugin-emit-notification.md`** — design doc,
-> version: feature/plugin-emit-notification-v2
-> (commits `f96508f4` → `9ec78817`)
+>
 
-If you're integrating the plugin with a custom host, that document is
-the authoritative reference for the `NotificationOptions` contract
-and the metadata merge semantics.
+## SSE Migration (v0.5.0+)
 
-## Notification payload (v0.4.0+)
+> **TL;DR**: stop depending on `env.notify`. The plugin now pushes events
+> over SSE. Connect with `new EventSource('/api/events')` (browser) or
+> `http.get(...)` (Node).
 
-When a task reaches a terminal status, the plugin calls
-`env.notify(...)` with a `visualization_ready` payload. The host's
-`NotificationChannel` (default: `EventBusNotificationChannel`) re-emits
-this on the env event bus as `plugin.notification.visualization_ready`.
-
-The payload looks like:
+### Before (v0.4.0)
 
 ```ts
-{
-  type: "visualization_ready",   // == NOTIFICATION_TYPE_VISUALIZATION_READY
-  title: "Task #1234 completed",
-  content: [
-    "Task: solve the bug",
-    "Status: completed",
-    "Visualization: http://127.0.0.1:7788/task/1234",
-  ].join("\n"),
-  metadata: {
-    taskId: 1234,
-    terminalStatus: "completed",
-    url: "http://127.0.0.1:7788/task/1234",
-    taskTitle: "solve the bug",        // when present in the hook payload
-    sessionId: "sess-xyz",            // when present in the hook payload
-    pluginName: "roy-plugin-task-show",
-    pluginVersion: "0.4.0",           // sync with host v2 (Task #N/A)
-    notificationTimestamp: 1718000000000,  // captured at emit time (Date.now())
-  },
-}
+// Plugin called env.notify({type:"visualization_ready", ...}).
+// Host's EventBusNotificationChannel re-emitted on env event bus:
+//   env.pushEnvEvent({type:"plugin.notification.visualization_ready", ...})
+// Subscribers (CLI / IM) listened on the env event bus.
 ```
 
-The `pluginName` / `pluginVersion` pair lets subscribers correlate the
-event with the plugin that emitted it (useful when multiple versions
-of the same plugin are installed in different workspaces). The
-`notificationTimestamp` is captured at emit time and is distinct from
-the host's `event.timestamp` (which the host stamps at
-`pushEnvEvent` call time) — useful for measuring queue / delivery
-latency downstream.
-
-### Subscribing to the notification
-
-The cleanest way to surface the URL to users is to subscribe to the
-env event bus for `plugin.notification.visualization_ready`. Example
-(in the host, e.g. `packages/cli`):
+### After (v0.5.0+)
 
 ```ts
-import { NOTIFICATION_TYPE_VISUALIZATION_READY } from "@.../roy-plugin-task-show";
-
-env.eventBus.on(
-  `plugin.notification.${NOTIFICATION_TYPE_VISUALIZATION_READY}`,
-  (event) => {
-    const { taskId, url, terminalStatus, taskTitle } = event.metadata;
-    // Render the URL in the chat / send a message / open the browser, etc.
-    console.log(`📊 Task #${taskId} ${terminalStatus}: ${url}`);
-  },
-);
+// Plugin emits via in-process EventBus; HTTP server streams frames
+// over /api/events. Frontend connects with EventSource — no host
+// NotificationChannel required.
+const source = new EventSource("/api/events");
+source.addEventListener("task.completed", (ev) => {
+  const { taskId, data } = JSON.parse(ev.data);
+  console.log(`Task ${taskId} → ${data.terminalStatus}`);
+});
 ```
 
-The plugin also exposes the URL directly via
-`TaskShowPlugin.getVisualizationUrl(taskId)` for callers that need it
-synchronously.
+### Why we changed
 
-## env.notify Migration (v0.4.0+)
+1. **No host dependency**: the SSE stream is served by the plugin's own
+   HTTP server. Works with any roy-agent host — no NotificationChannel
+   required.
+2. **Incremental updates**: instead of one-shot "URL injection" on
+   terminal status, the frontend receives a frame for *every*
+   meaningful change (created / recorded / updated / completed). The
+   page updates as the agent works, not after.
+3. **Progress bar + timeline**: with continuous updates, the frontend
+   can show a live progress bar (tool call count) and a real-time
+   timeline without manual refresh.
+4. **Simpler host contract**: removed `env.notify` plumbing from the
+   plugin surface. The plugin's `PluginEnvLike` type no longer mentions
+   `notify`.
 
-> **TL;DR**: stop mutating tool result output. Call `env.notify` instead.
+### Backward compatibility
 
-### Before (v0.3.0 and earlier)
+The plugin no longer mutates tool result output (that mechanism was
+removed in v0.4.0). Pin to `roy-plugin-task-show@0.4.x` if you depend
+on the legacy `env.notify` consumer path.
 
-```ts
-// Plugin mutated ctx.result.output by appending a markdown banner.
-await plugin.onTaskAfterComplete({
-  data: { task: { id: 1234, status: "completed", title: "demo" } },
-});
-// ctx.result.output now contains:
-//   "...original...\n---\n📊 可视化工具调用链路: <http://...>"
-```
+## Port handling
 
-### After (v0.4.0+)
+The plugin binds a local `http.Server` on the port you configure (default
+`7788`). If that port is busy (`EADDRINUSE`), the server **probes
+`port + 1`, `port + 2`, … in ascending order** until a free port is
+found. Each skipped port emits a `WARN` log so it's easy to spot:
 
-```ts
-// Plugin calls env.notify; the host's NotificationChannel pipeline
-// re-emits it on the env event bus. ctx.result.output is preserved.
-await plugin.onTaskAfterComplete({
-  data: {
-    task: { id: 1234, status: "completed", title: "demo" },
-    terminalStatus: "completed",
-  },
-});
-// env.notify was called with { type: "visualization_ready", ... }
-// ctx.result.output is unchanged.
+```
+[task-show:server] WARN Port 7788 busy — trying 7789
+[task-show:server] WARN Port 7789 busy — trying 7790
+[task-show:server] INFO  HTTP service listening on http://127.0.0.1:7790/ (port rewritten from 7788 due to conflict)
 ```
 
-### Why we changed
-
-1. **Decoupling**: tool result output is owned by the tool (and the
-   LLM that consumes it). Mutating it as a side effect of "the task is
-   done" is leaky — the visualization URL is not part of the tool's
-   output, it's a UI/notification concern.
-2. **Multiple subscribers**: with `env.notify`, the env event bus fans
-   the URL out to every subscriber (CLI, IM, webhooks, custom loggers).
-   Mutating output only surfaces the URL in the LLM's next prompt.
-3. **Pluggable delivery**: `EventBusNotificationChannel` is the default,
-   but hosts can register `LarkCliNotificationChannel` (legacy, sends a
-   Feishu message directly) or a custom `WebhookChannel` without
-   touching the plugin. The plugin just calls `env.notify` and walks
-   away.
-
-### Backward compatibility
-
-The legacy `injectVisualizationUrl()` helper in `src/url-injector.ts`
-is marked `@deprecated` but is still exported. Set
-`urlInjectEnabled: true` in the plugin config to opt back into the
-mutation behavior — useful for test harnesses and very old hosts that
-don't have the `NotificationChannel` abstraction.
+Guarantees:
+
+- Only `EADDRINUSE` triggers a retry. Any other `listen()` error
+  (`EACCES`, `ENOTSUP`, …) is surfaced as a normal rejection — the
+  caller still owns the error and can decide what to do.
+- Probing **never wraps** past `65535` and **never** falls back to
+  `listen(0)` (OS-assigned ephemeral port). If everything in
+  `[port, 65535]` is busy, `start()` rejects with a clear error so
+  you know to free a port or move the host elsewhere.
+- `ServerInfo.portRewritten` is `true` whenever the bound port differs
+  from `cfg.port`. The same flag is exposed on the `ServerInfo` object
+  passed to whoever called `start()`.
+- The probing helper (`listenWithProbing()` in `src/server.ts`) is
+  exported so the same logic can be reused or unit-tested in isolation.
+
+If you prefer the OS-assigned-port semantics (e.g. for tests), set
+`port: 0` in the config — the server will then call `listen(0)`
+directly, no probing, and `portRewritten` stays `false`.
 
 ## Development
 
@@ -368,7 +434,7 @@ bun run typecheck
 # Build (emit dist/)
 bun run build
 
-# Run unit tests (collector, url-injector, server, plugin, plugin-notify)
+# Run unit tests (63 tests across 7 files)
 bun test
 
 # End-to-end check (boots the service, hits it, asserts response)
@@ -410,54 +476,71 @@ It also recognizes (in priority order):
 If no task id can be recovered, the call lands in a synthetic session so
 the visualization still works.
 
-### `task:after.complete` (preferred, consumed)
-
-The plugin accepts the standard `TaskCompleteResultContext`:
+### `task:before.create` (v0.5.0+)
 
 ```ts
 {
-  task: { id: number, status: 'completed' | 'failed' | 'cancelled' | 'timeout', title?: string },
-  terminalStatus: 'completed' | 'failed' | 'cancelled' | 'timeout',
-  changes: Partial<UpdateTaskOptions>,
-  sessionId: string,
-  tagService: TagService,
+  data: { task: { id: number, title?: string } }
+  // OR flat: { taskId: number, title?: string }
 }
 ```
 
-Because the host pre-filters to terminal transitions, no plugin-side status
-filtering is needed. The plugin dedupes by `taskId` against the legacy hook
-below.
+If a session already exists for the task id (re-create / retry), its
+`toolCalls` are preserved.
 
-### `task:after.update` (legacy fallback, consumed)
+### `task:after.create` (v0.5.0+)
+
+Same payload as `task:before.create`. Useful for hosts that don't emit
+`task:before.create`; the plugin opens the session here and broadcasts
+`task.created`.
 
-On hosts predating the `AFTER_COMPLETE` hook point, the plugin also subscribes
-to `TaskUpdateResultContext`:
+### `task:after.complete` (preferred, consumed)
+
+```ts
+{
+  data: {
+    task: { id: number, status: 'completed' | 'failed' | 'cancelled', title?: string },
+    terminalStatus: 'completed' | 'failed' | 'cancelled',
+    changes: Partial<UpdateTaskOptions>,
+    sessionId: string,
+    tagService: TagService,
+  }
+}
+```
+
+### `task:after.update` (legacy fallback, consumed)
 
 ```ts
 { data: { task: { id: number, status: string, title?: string }, changes, tagService } }
 ```
 
-The handler filters for terminal status (`completed` / `failed` / `cancelled` /
-`timeout`) and dedupes — if `AFTER_COMPLETE` also fires (it can, on a host
-that supports both hooks), the URL is injected exactly once.
+The handler filters for terminal status (`completed` / `failed` /
+`cancelled`) and dedupes — if `AFTER_COMPLETE` also fires (it can, on a
+host that supports both hooks), only one `task.completed` event is
+broadcast.
 
 ## Limitations & follow-ups
 
-- **Memory-only**: the collector keeps data in memory only. Restarting the
-  host process drops everything. Persisting to a file would be a small
-  follow-up.
-- **Single host**: if you launch multiple `roy-agent` instances on the same
-  machine, change the `port` to avoid clashes (the service falls back to a
-  random port automatically, but the URL won't be predictable).
-- **Mermaid CDN**: the frontend loads `mermaid@10` from jsDelivr. Air-gapped
-  deployments should vendor a copy locally.
-- **No agent-level hooks**: the plugin currently does not subscribe to
-  `agent:after.execute` because the agent tool loop already fires
-  `tool:after.execute` per tool. If you want a "task finished" view that
-  includes the final agent message, listen to `agent:after.execute` too.
-- **No file persistence**: data lives only in memory. A future improvement
-  would be a tiny SQLite sink so a restart still shows recent tasks.
+- **Memory-only**: the collector keeps data in memory only. Restarting
+  the host process drops everything. Persisting to a file would be a
+  small follow-up.
+- **Single host**: if you launch multiple `roy-agent` instances on the
+  same machine, change the `port` to avoid clashes. The server probes
+  `port + 1`, `port + 2`, ... in ascending order until a free TCP port
+  is found (sequential port probing — no random / ephemeral fallback).
+  If everything from `port` through `65535` is busy, `start()` rejects
+  with a clear error so you know to free a port or move the host
+  elsewhere.
+- **Mermaid CDN**: the frontend loads `mermaid@10` from jsDelivr.
+  Air-gapped deployments should vendor a copy locally.
+- **No file persistence**: data lives only in memory. A future
+  improvement would be a tiny SQLite sink so a restart still shows
+  recent tasks.
+- **SSE-only push**: the bundled frontend uses EventSource as the
+  primary update channel. A 3-second polling fallback covers older
+  browsers and proxies that strip SSE, but it's a degraded experience.
+  WebSocket support is a possible future addition.
 
 ## License
 
-MIT
+MIT