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

package/dist/url-injector.d.ts

@@ -1,22 +1,21 @@
 /**
- * @fileoverview Mutates a ToolResult output to append a visualization URL.
+ * @fileoverview URL builders for the visualization page.
  *
- * ## ⚠️ DEPRECATED as of v0.4.0
+ * ## ⚠️ DEPRECATED as of v0.5.0
  *
- * `injectVisualizationUrl()` mutates `result.output` in-place by appending a
- * markdown link. v0.4.0+ plugins should call `env.notify({type:"visualization_ready", ...})`
- * instead — see `TaskShowPlugin.emitVisualizationReady()` in `src/plugin.ts`.
+ * This module used to also export `injectVisualizationUrl()` /
+ * `appendVisualizationBanner()` for mutating tool result output. Those
+ * helpers were removed in v0.5.0 — the plugin no longer mutates tool
+ * result output. Reach-out happens via the SSE event stream broadcast
+ * by the local HTTP service.
  *
- * The mutation path is kept as a fallback for callers (e.g. custom test
- * harnesses or older hosts) that need to mutate a result directly. It will
- * be removed in v2.0.
+ * Only the pure URL builders remain. They are still used internally by
+ * the plugin (to compute `visualizationUrl` on each TaskSession) and may
+ * be useful for tests / custom callers that want to display the URL.
  *
- * The mutation itself is **non-destructive** — we never alter or trim the
- * original content, only append after a divider so LLM agents can still
- * parse the response.
- *
- * @deprecated since v0.4.0 — use `env.notify` (host) or
- *   `TaskShowPlugin.emitVisualizationReady()` (plugin) instead.
+ * The mutation helpers (`injectVisualizationUrl`, `appendVisualizationBanner`)
+ * are gone in v0.5.0. If you depend on the old mutation behavior, pin to
+ * `roy-plugin-task-show@0.4.x`.
  */
 import type { TaskShowConfig } from "./types.js";
 /**
@@ -29,38 +28,4 @@ export declare function buildVisualizationUrl(cfg: Pick<TaskShowConfig, "host" |
  * mention "see all recent tasks" alongside a single URL).
  */
 export declare function buildIndexUrl(cfg: Pick<TaskShowConfig, "host" | "port">): string;
-/**
- * Result of an injection attempt — we want callers (especially tests) to be
- * able to verify whether a result was actually modified.
- */
-export interface InjectionResult {
-    /** True iff the output text was actually mutated. */
-    mutated: boolean;
-    /** The final visualization URL we appended. */
-    url?: string;
-    /** The full output AFTER mutation. */
-    output?: string;
-}
-/**
- * Append the visualization URL to a tool result.
- *
- * - The mutation only runs when `enabled` is true.
- * - The hook context shape is intentionally permissive (any) because the
- *   ToolResult shape across versions can drift slightly. We only depend on
- *   a string `output`.
- *
- * @deprecated since v0.4.0 — use `env.notify` (host) or
- *   `TaskShowPlugin.emitVisualizationReady()` (plugin) instead. This
- *   function will be removed in v2.0.
- */
-export declare function injectVisualizationUrl(opts: {
-    ctx?: any;
-    cfg: TaskShowConfig;
-    taskId: number;
-}): InjectionResult;
-/**
- * Helper for tests / non-tool callers — given a raw string output, returns a
- * new string with the banner appended. Does not mutate the input.
- */
-export declare function appendVisualizationBanner(output: string, cfg: Pick<TaskShowConfig, "host" | "port">, taskId: number | string, extraLines?: string[]): string;
 //# sourceMappingURL=url-injector.d.ts.map

package/dist/url-injector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url-injector.d.ts","sourceRoot":"","sources":["../src/url-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,EAC1C,MAAM,EAAE,MAAM,GAAG,MAAM,GACtB,MAAM,CAIR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,GACzC,MAAM,CAGR;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,eAAe,CAyBlB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,EAC1C,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,UAAU,GAAE,MAAM,EAAO,GACxB,MAAM,CAMR"}
+{"version":3,"file":"url-injector.d.ts","sourceRoot":"","sources":["../src/url-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,EAC1C,MAAM,EAAE,MAAM,GAAG,MAAM,GACtB,MAAM,CAIR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,GACzC,MAAM,CAGR"}

package/dist/url-injector.js

@@ -1,22 +1,21 @@
 /**
- * @fileoverview Mutates a ToolResult output to append a visualization URL.
+ * @fileoverview URL builders for the visualization page.
  *
- * ## ⚠️ DEPRECATED as of v0.4.0
+ * ## ⚠️ DEPRECATED as of v0.5.0
  *
- * `injectVisualizationUrl()` mutates `result.output` in-place by appending a
- * markdown link. v0.4.0+ plugins should call `env.notify({type:"visualization_ready", ...})`
- * instead — see `TaskShowPlugin.emitVisualizationReady()` in `src/plugin.ts`.
+ * This module used to also export `injectVisualizationUrl()` /
+ * `appendVisualizationBanner()` for mutating tool result output. Those
+ * helpers were removed in v0.5.0 — the plugin no longer mutates tool
+ * result output. Reach-out happens via the SSE event stream broadcast
+ * by the local HTTP service.
  *
- * The mutation path is kept as a fallback for callers (e.g. custom test
- * harnesses or older hosts) that need to mutate a result directly. It will
- * be removed in v2.0.
+ * Only the pure URL builders remain. They are still used internally by
+ * the plugin (to compute `visualizationUrl` on each TaskSession) and may
+ * be useful for tests / custom callers that want to display the URL.
  *
- * The mutation itself is **non-destructive** — we never alter or trim the
- * original content, only append after a divider so LLM agents can still
- * parse the response.
- *
- * @deprecated since v0.4.0 — use `env.notify` (host) or
- *   `TaskShowPlugin.emitVisualizationReady()` (plugin) instead.
+ * The mutation helpers (`injectVisualizationUrl`, `appendVisualizationBanner`)
+ * are gone in v0.5.0. If you depend on the old mutation behavior, pin to
+ * `roy-plugin-task-show@0.4.x`.
  */
 /**
  * Build the public URL the visualization lives at. Exposed so that unit tests
@@ -35,48 +34,4 @@ export function buildIndexUrl(cfg) {
     const host = cfg.host === "0.0.0.0" ? "localhost" : cfg.host;
     return `http://${host}:${cfg.port}/`;
 }
-/**
- * Append the visualization URL to a tool result.
- *
- * - The mutation only runs when `enabled` is true.
- * - The hook context shape is intentionally permissive (any) because the
- *   ToolResult shape across versions can drift slightly. We only depend on
- *   a string `output`.
- *
- * @deprecated since v0.4.0 — use `env.notify` (host) or
- *   `TaskShowPlugin.emitVisualizationReady()` (plugin) instead. This
- *   function will be removed in v2.0.
- */
-export function injectVisualizationUrl(opts) {
-    const { ctx, cfg, taskId } = opts;
-    if (!cfg.urlInjectEnabled)
-        return { mutated: false };
-    if (!ctx)
-        return { mutated: false };
-    const result = ctx?.result ?? ctx?.toolResult ?? null;
-    if (!result || typeof result.output !== "string") {
-        return { mutated: false };
-    }
-    const url = buildVisualizationUrl(cfg, taskId);
-    const banner = `\n\n---\n📊 **可视化工具调用链路**: <${url}>\n` +
-        `(浏览器访问即可查看 mermaid 流程图：每个工具调用、参数、结果摘要、耗时)`;
-    const newOutput = result.output + banner;
-    result.output = newOutput;
-    // Make sure the URL is also recorded in metadata — some chat clients
-    // prefer to render markdown from a structured field.
-    if (typeof result.metadata === "object" && result.metadata !== null) {
-        result.metadata.task_visualization_url = url;
-    }
-    return { mutated: true, url, output: newOutput };
-}
-/**
- * Helper for tests / non-tool callers — given a raw string output, returns a
- * new string with the banner appended. Does not mutate the input.
- */
-export function appendVisualizationBanner(output, cfg, taskId, extraLines = []) {
-    const url = buildVisualizationUrl(cfg, taskId);
-    const banner = `\n\n---\n📊 **可视化工具调用链路**: <${url}>` +
-        (extraLines.length ? "\n" + extraLines.map((l) => `> ${l}`).join("\n") : "");
-    return output + banner;
-}
 //# sourceMappingURL=url-injector.js.map

package/dist/url-injector.js.map

@@ -1 +1 @@
-{"version":3,"file":"url-injector.js","sourceRoot":"","sources":["../src/url-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAA0C,EAC1C,MAAuB;IAEvB,qDAAqD;IACrD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IAC7D,OAAO,UAAU,IAAI,IAAI,GAAG,CAAC,IAAI,SAAS,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;AACjF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,GAA0C;IAE1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IAC7D,OAAO,UAAU,IAAI,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC;AACvC,CAAC;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAItC;IACC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAElC,IAAI,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACrD,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAEpC,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,GAAG,EAAE,UAAU,IAAI,IAAI,CAAC;IACtD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACjD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC/C,MAAM,MAAM,GACV,+BAA+B,GAAG,KAAK;QACvC,2CAA2C,CAAC;IAC9C,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACzC,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC;IAE1B,qEAAqE;IACrE,qDAAqD;IACrD,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QACnE,MAAM,CAAC,QAAoC,CAAC,sBAAsB,GAAG,GAAG,CAAC;IAC5E,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAc,EACd,GAA0C,EAC1C,MAAuB,EACvB,aAAuB,EAAE;IAEzB,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC/C,MAAM,MAAM,GACV,+BAA+B,GAAG,GAAG;QACrC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/E,OAAO,MAAM,GAAG,MAAM,CAAC;AACzB,CAAC"}
+{"version":3,"file":"url-injector.js","sourceRoot":"","sources":["../src/url-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAA0C,EAC1C,MAAuB;IAEvB,qDAAqD;IACrD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IAC7D,OAAO,UAAU,IAAI,IAAI,GAAG,CAAC,IAAI,SAAS,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;AACjF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,GAA0C;IAE1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IAC7D,OAAO,UAAU,IAAI,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC;AACvC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-setting/roy-plugin-task-show",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "roy-agent plugin: visualize task solving process via tool call flow on a local web service",
   "type": "module",
   "main": "dist/index.js",

package/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "@ai-setting/roy-plugin-task-show",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "tool-plugin",
-  "description": "Visualize the tool call chain of a task on a local web service and notify via env.notify. v0.4.0+: env.notify({type:\"visualization_ready\"}) on terminal status (preferred). Subscribes to tool:before.execute (for self-managed timing), tool:after.execute, task:after.complete (preferred, 2026-07-10+) and task:after.update (legacy fallback).",
+  "description": "Visualize the tool call chain of a task on a local web service with real-time SSE updates. v0.5.0+: page refreshes stream over GET /api/events (Server-Sent Events). Subscribes to tool:before.execute, tool:after.execute, task:before.create, task:after.create, task:after.complete (preferred, 2026-07-10+), and task:after.update (legacy fallback).",
   "main": "dist/index.js",
   "hooks": [
     {
@@ -11,15 +11,23 @@
     },
     {
       "point": "tool:after.execute",
-      "purpose": "Collect every tool invocation: tool name, args, result, timing, success"
+      "purpose": "Collect every tool invocation: tool name, args, result, timing, success. Broadcasts a `tool.recorded` SSE event so the frontend timeline + progress bar update live."
+    },
+    {
+      "point": "task:before.create",
+      "purpose": "Open a fresh TaskSession before the task runs (v0.5.0+). Mints the visualization URL and broadcasts a `task.created` SSE event so the UI can render the card immediately, even if no tool call fires."
+    },
+    {
+      "point": "task:after.create",
+      "purpose": "Mark the session ready for tracking (v0.5.0+). For hosts that emit only this hook (no `task:before.create`), the plugin opens the session here. Broadcasts a `task.created` SSE event when the session is newly minted."
     },
     {
       "point": "task:after.complete",
-      "purpose": "PREFERRED hook point (roy-agent 2026-07-10+). When a task transitions to a terminal status (completed/failed/cancelled/timeout), finalize the session and emit a `visualization_ready` notification via `env.notify`. terminalStatus field is explicit — no status filtering required. The URL is delivered through the host's NotificationChannel pipeline (default: EventBusNotificationChannel) instead of mutating tool result output."
+      "purpose": "PREFERRED hook point (roy-agent 2026-07-10+). When a task transitions to a terminal status (completed/failed/cancelled), finalize the session and broadcast a `task.completed` SSE event. terminalStatus field is explicit — no status filtering required. The handler dedupes against any `task:after.update` that may also fire on the same transition."
     },
     {
       "point": "task:after.update",
-      "purpose": "LEGACY fallback. Hosts predating the AFTER_COMPLETE hook point only expose AFTER_UPDATE; the plugin filters for terminal status internally and dedupes against any AFTER_COMPLETE that might also fire on the new code path."
+      "purpose": "GENERIC status update hook (v0.5.0+). Used for non-terminal transitions (running → paused → running) AND as a legacy fallback for hosts predating the AFTER_COMPLETE hook point. Broadcasts `task.updated` for non-terminal status, `task.completed` for terminal status. The internal dedup set guarantees at most one terminal broadcast per task even if both hooks fire."
     }
   ],
   "commands": [
@@ -49,17 +57,31 @@
       "default": 50,
       "description": "Maximum number of completed tasks to keep in memory (older ones are evicted)"
     },
-    "urlInjectEnabled": {
-      "type": "boolean",
-      "default": false,
-      "description": "DEPRECATED (v0.4.0+). Append a 📊 visualization URL to the last tool result when a task completes. The plugin no longer mutates tool result output by default — use env.notify instead. Set to true only for legacy hosts that pre-date NotificationChannel."
-    },
     "publicDir": {
       "type": "string",
       "default": "public",
       "description": "Directory holding the static visualization frontend (HTML/JS/CSS)"
     }
   },
+  "endpoints": {
+    "index": "GET / — index of recent task sessions",
+    "taskDetail": "GET /task/:taskId — detail page (mermaid flow + tables)",
+    "apiSessions": "GET /api/sessions — JSON list of sessions",
+    "apiSessionDetail": "GET /api/sessions/:taskId — JSON detail of one session",
+    "apiEvents": "GET /api/events — Server-Sent Events stream (real-time push)",
+    "static": "GET /static/* — static frontend assets (CSS/JS)"
+  },
+  "sse": {
+    "events": [
+      "snapshot — initial state dump on connect",
+      "task.created — new task session opened",
+      "task.updated — non-terminal status change",
+      "task.completed — task transitioned to a terminal status",
+      "tool.recorded — tool call appended to a session"
+    ],
+    "heartbeatMs": 15000,
+    "snapshotFrame": "event: snapshot\ndata: {type:'snapshot', data:{sessions:[...]}}\n\n"
+  },
   "roy-agent": {
     "minVersion": "1.6.0",
     "extends": "BasePlugin",
@@ -67,4 +89,4 @@
   },
   "repository": "github:ai-setting/roy-plugin-task-visualize",
   "bugs": "https://github.com/ai-setting/roy-plugin-task-visualize/issues"
-}
+}