@qoniai/qoni 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.6.0 - 2026-09-23
+
+### Added
+
+- Deliver `browserLiveUrlChanged` on semantic run streams when the browser
+  viewer URL changes. Applications can follow the active tab instead of
+  remaining on the initial blank page. The event includes the live viewer URL
+  and refresh hint, without exposing the private CDP URL in `event.data`.
+
 ## 0.5.2 - 2026-09-23
 
 ### Fixed

package/README.md

@@ -687,6 +687,7 @@ that type:
 //     "message"        { text, role }
 //     "interaction"    the typed Interaction object (HITL) — see Interactions
 //     "screenshot"     { pageUrl?, step? }   + the decoded image on event.image
+//     "browserLiveUrlChanged" { liveUrl, supportsLivePump, forceViewerReload, providerSessionId? }
 //     "done"           { output, succeeded, terminalReason }
 // Common to every event: runId, at (ISO 8601), isTerminal (true only for "done"),
 // raw (the original wire event — escape hatch).
@@ -696,11 +697,17 @@ Each product handle is typed to its own subset:
 
 | Product | `event.type` set |
 |---|---|
-| Do Anything | core: `progress` / `message` / `interaction` / `screenshot` / `done` |
+| Do Anything | core: `progress` / `message` / `interaction` / `screenshot` / `browserLiveUrlChanged` / `done` |
 | Web Search | core + `resultsReady` |
 | Deep Research | core + `phase` / `sectionReady` (the outline gate arrives as an `interaction`) |
 | Track (`MonitorHandle`) | core + `monitorCreated` / `triggered` / `checkCompleted` |
 
+For a live browser preview, listen for `browserLiveUrlChanged` and show
+`event.data.liveUrl` in your viewer. A run can switch browser tabs after its
+first URL arrives, so update the viewer on later events too. Remount an
+existing viewer when `forceViewerReload` is true. The URL grants access to the
+browser view; keep it out of public logs.
+
 Dropped connections reconnect automatically with `Last-Event-ID` catch-up; the iterator ends at the run's terminal (`done`) event.
 For complete audit/observability capture, `onWireEvent` receives every original
 SSE frame before semantic normalization or filtering; `onReconnect` receives

package/README.zh-CN.md

@@ -620,6 +620,7 @@ type QoniResponse<T> = {
 //     "message"        { text, role }
 //     "interaction"    带类型的 Interaction 对象（HITL）—— 见「交互」一节
 //     "screenshot"     { pageUrl?, step? }   + 解码后的图在 event.image
+//     "browserLiveUrlChanged" { liveUrl, supportsLivePump, forceViewerReload, providerSessionId? }
 //     "done"           { output, succeeded, terminalReason }
 // 公共字段:runId、at(ISO 8601)、isTerminal(仅 "done" 为 true)、raw(原始 wire 事件,逃生舱)。
 ```
@@ -628,11 +629,13 @@ type QoniResponse<T> = {
 
 | 产品 | `event.type` 集合 |
 |---|---|
-| Do Anything | 核心:`progress` / `message` / `interaction` / `screenshot` / `done` |
+| Do Anything | 核心:`progress` / `message` / `interaction` / `screenshot` / `browserLiveUrlChanged` / `done` |
 | Web Search | 核心 + `resultsReady` |
 | Deep Research | 核心 + `phase` / `sectionReady`（大纲审批走 `interaction`） |
 | Track（`MonitorHandle`） | 核心 + `monitorCreated` / `triggered` / `checkCompleted` |
 
+展示实时浏览器时，监听 `browserLiveUrlChanged`，用 `event.data.liveUrl` 更新预览地址。任务执行期间可能切换标签页，因此不能只使用第一次收到的地址。`forceViewerReload` 为 true 时重载已有预览。live URL 可访问浏览器画面，不要写入公开日志。
+
 断线会带 `Last-Event-ID` 自动重连续传；迭代器在终态事件后自动结束。
 需要完整审计/可观测性证据时，`onWireEvent` 会在语义归一化和过滤之前收到每一个原始 SSE 帧；
 `onReconnect` 会收到重试次数和最后事件 id。应用逻辑继续使用稳定的 `RunEvent`，原始回调只用于证据与诊断。

package/dist/index.cjs

@@ -278,6 +278,8 @@ var QoniEventTypes = {
   Interaction: "interaction",
   /** A live screenshot frame (opt in with `capture: { screenshots: true }`); image on `event.image`. */
   Screenshot: "screenshot",
+  /** The browser viewer moved to a new page or needs a fresh attachment. Use `event.data.liveUrl` for the live preview. */
+  BrowserLiveUrlChanged: "browserLiveUrlChanged",
   /** Terminal — the run finished; outcome + output in `event.data` (cost is on the `RunResult`). */
   Done: "done",
   // --- Web Search ---
@@ -408,7 +410,6 @@ var WIRE_TO_SEMANTIC = {
   "run.recording_started": "progress",
   "run.recording_paused": "progress",
   "run.recording_finalized": "progress",
-  "run.browser_live_url_changed": "progress",
   // side-channel
   "run.feedback_submitted": "progress"
 };
@@ -470,6 +471,18 @@ function normalizeRunEvent(wire, options = {}) {
       return { ...base, type: "screenshot", data: sData, image, isTerminal: false };
     }
   }
+  if (wireType === "run.browser_live_url_changed") {
+    const liveUrl = asString(c.liveUrl);
+    if (!liveUrl) return null;
+    const data2 = {
+      liveUrl,
+      supportsLivePump: c.supportsLivePump === true,
+      forceViewerReload: c.forceViewerReload === true
+    };
+    const providerSessionId = asString(c.providerSessionId);
+    if (providerSessionId) data2.providerSessionId = providerSessionId;
+    return { ...base, type: "browserLiveUrlChanged", data: data2, isTerminal: false };
+  }
   if (wireType === INTERACTION) {
     const interaction = normalizeInteraction(payload);
     if (interaction) {