@qoniai/qoni 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # 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
+
+- Keep permission errors concise instead of appending every known scope.
+- Explain how to enable a permission policy when an AccessKey has no allowed
+  scopes. Preserve the backend error code and request ID for diagnosis.
+
 ## 0.5.1 - 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
@@ -727,7 +734,7 @@ All error classes are exported and can be matched with `instanceof`:
 | --- | --- | --- |
 | `QoniValidationError` | Local input check failed before any request (bad scope string, silent delegation missing a user). | Fix the call — the message states the correct form. |
 | `QoniAuthError` | AK/SK signing rejected by Qoni (bad/rotated credentials). | Check `accessKey` / `secretKey`. |
-| `QoniPermissionDeniedError` | The delegation token lacks a required scope (403). | Re-`delegateToken` with the missing scope. |
+| `QoniPermissionDeniedError` | The AccessKey or delegation token lacks a required scope (403). | Check the AccessKey permission policy and request the missing scope with `delegateToken`. |
 | `QoniTokenExpiredError` | The delegation / product token expired. | Mint a fresh token and retry. |
 | `QoniDelegationRequiredError` | A product call was made without `token`, or with a raw token the gateway won't accept directly. | Pass `delegation.data.token` to the product call. |
 | `QoniRateLimitError` | Rate limited (429). | Back off and retry (`retryable === true`). |
@@ -777,6 +784,7 @@ Common first-run errors:
 | --- | --- | --- |
 | `agent must be a string` | The online delegation API currently expects `agent` to be a string id. | Pass `agent: "memory-agent"` rather than an object. |
 | `eak.delegation.user_not_bound` | The `userId` is not in the GenAuth userpool bound to this Qoni credential. | Use a real user id from `currentUser` or from the same bound userpool. |
+| `eak.delegation.no_allowed_scopes` | The AccessKey has no permission scopes enabled. | In Qoni Console, open its Permission scope settings and enable the policy required by this call. |
 | `eak.genauth.userpool_binding_missing` | The AK/SK is not bound to a GenAuth userpool, so `genauth.users.*` cannot obtain a management token. | Bind the Qoni credential to the target GenAuth userpool before calling user management APIs. |
 | `eak.genauth.userpool_owner_missing` | The bound GenAuth userpool has no resolvable owner user for management-token signing. | Fix the GenAuth userpool owner data or binding. |
 | `eak.token_exchange.upstream_failed` with `unauthorized_client` or `grant_type is not enabled` | Delegation succeeded, but the managed delegation app is missing token-exchange grant support or has drifted from the tenant binding. | Repair the managed delegation app binding before calling GUMem or WebAgent product capabilities. |

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`，原始回调只用于证据与诊断。
@@ -657,7 +660,7 @@ type QoniEvent<T = unknown> = {
 | --- | --- | --- |
 | `QoniValidationError` | 请求发出前的本地校验失败（scope 字符串格式错、silent 委托缺 user）。 | 按消息修正调用——消息里给出正确写法。 |
 | `QoniAuthError` | AK/SK 签名被 Qoni 拒绝（凭据错误/已轮换）。 | 检查 `accessKey` / `secretKey`。 |
-| `QoniPermissionDeniedError` | delegation token 缺所需 scope（403）。 | 带上缺失 scope 重新 `delegateToken`。 |
+| `QoniPermissionDeniedError` | AccessKey 或 delegation token 缺少所需 scope（403）。 | 检查 AccessKey 权限策略，并在 `delegateToken` 中申请所需 scope。 |
 | `QoniTokenExpiredError` | delegation / 产品 token 过期。 | 重新 mint token 再试。 |
 | `QoniDelegationRequiredError` | 产品调用没带 `token`，或带的是网关不接受的裸 token。 | 把 `delegation.data.token` 传给产品调用。 |
 | `QoniRateLimitError` | 被限流（429）。 | 退避后重试（`retryable === true`）。 |
@@ -706,6 +709,7 @@ try {
 | --- | --- | --- |
 | `agent must be a string` | 当前线上 delegation API 期望 `agent` 是字符串 ID。 | 使用 `agent: "memory-agent"`，不要传对象。 |
 | `eak.delegation.user_not_bound` | `userId` 不属于该 Qoni credential 绑定的 GenAuth userpool。 | 使用 `currentUser` 返回的真实用户 ID，或确认用户来自同一个绑定 userpool。 |
+| `eak.delegation.no_allowed_scopes` | AccessKey 没有启用任何权限 scope。 | 在 Qoni Console 的 Permission scope 设置中启用本次调用所需的策略。 |
 | `eak.genauth.userpool_binding_missing` | AK/SK 没有绑定 GenAuth userpool，`genauth.users.*` 无法换取 management token。 | 先把 Qoni credential 绑定到目标 GenAuth userpool。 |
 | `eak.genauth.userpool_owner_missing` | 绑定的 GenAuth userpool 找不到可用于签发 management token 的 owner 用户。 | 修复 GenAuth userpool owner 数据或绑定。 |
 | `eak.token_exchange.upstream_failed` 且包含 `unauthorized_client` 或 `grant_type is not enabled` | Delegation 已成功，但 managed delegation app 缺少 token-exchange grant，或租户绑定发生漂移。 | 先修复 managed delegation app 绑定，再调用 GUMem 或 WebAgent 产品能力。 |

package/dist/index.cjs

@@ -104,81 +104,6 @@ function buildSignedHeaders(credentials, method, pathname, payload) {
   return headers;
 }
 
-// src/scopes.ts
-var QoniScopes = {
-  GUMEM_SESSION_CREATE: "gumem.session:create",
-  GUMEM_MESSAGE_WRITE: "gumem.message:write",
-  GUMEM_MEMORY_READ: "gumem.memory:read",
-  GUMEM_MEMORY_WRITE: "gumem.memory:write",
-  GUMEM_MEMORY_DELETE: "gumem.memory:delete",
-  GUMEM_SEARCH_RUN: "gumem.search:run",
-  GUMEM_ADMIN_MANAGE: "gumem.admin:manage",
-  GUMEM_RESOURCE_WRITE: "gumem.resource:write",
-  GUMEM_ACTION_WRITE: "gumem.action:write",
-  GUMEM_ACTION_READ: "gumem.action:read",
-  GUMEM_PROFILE_READ: "gumem.profile:read",
-  // WebAgent products: exactly two verbs per product — `read` (observe) and
-  // `manage` (anything that changes execution state). See
-  // wa/docs/qoni-sdk-public-surface.md §3.
-  DO_ANYTHING_READ: "webagent.do_anything:read",
-  DO_ANYTHING_MANAGE: "webagent.do_anything:manage",
-  WEB_SEARCH_READ: "webagent.web_search:read",
-  WEB_SEARCH_MANAGE: "webagent.web_search:manage",
-  DEEP_RESEARCH_READ: "webagent.deep_research:read",
-  DEEP_RESEARCH_MANAGE: "webagent.deep_research:manage",
-  TRACK_READ: "webagent.track:read",
-  TRACK_MANAGE: "webagent.track:manage"
-};
-var QoniProductScopes = {
-  doAnything: [
-    QoniScopes.DO_ANYTHING_READ,
-    QoniScopes.DO_ANYTHING_MANAGE
-  ],
-  webSearch: [
-    QoniScopes.WEB_SEARCH_READ,
-    QoniScopes.WEB_SEARCH_MANAGE
-  ],
-  deepResearch: [
-    QoniScopes.DEEP_RESEARCH_READ,
-    QoniScopes.DEEP_RESEARCH_MANAGE
-  ],
-  track: [
-    QoniScopes.TRACK_READ,
-    QoniScopes.TRACK_MANAGE
-  ]
-};
-var KNOWN_SCOPES = Object.values(QoniScopes);
-var QoniScopeBundles = {
-  GUMEM_READONLY: [QoniScopes.GUMEM_MEMORY_READ, QoniScopes.GUMEM_PROFILE_READ],
-  GUMEM_SESSION_RECALL: [
-    QoniScopes.GUMEM_MEMORY_READ,
-    QoniScopes.GUMEM_MEMORY_WRITE,
-    QoniScopes.GUMEM_MESSAGE_WRITE
-  ],
-  GUMEM_WRITE: [
-    QoniScopes.GUMEM_SESSION_CREATE,
-    QoniScopes.GUMEM_MESSAGE_WRITE,
-    QoniScopes.GUMEM_ACTION_WRITE
-  ],
-  // One bundle per WebAgent product = [read, manage].
-  DO_ANYTHING: [
-    QoniScopes.DO_ANYTHING_READ,
-    QoniScopes.DO_ANYTHING_MANAGE
-  ],
-  WEB_SEARCH: [
-    QoniScopes.WEB_SEARCH_READ,
-    QoniScopes.WEB_SEARCH_MANAGE
-  ],
-  DEEP_RESEARCH: [
-    QoniScopes.DEEP_RESEARCH_READ,
-    QoniScopes.DEEP_RESEARCH_MANAGE
-  ],
-  TRACK: [
-    QoniScopes.TRACK_READ,
-    QoniScopes.TRACK_MANAGE
-  ]
-};
-
 // src/types.ts
 function isJsonObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -262,7 +187,7 @@ function errorFromPayload(status, payload, fallbackMessage) {
   const source = detailObject || (isJsonObject(payload) ? payload : {});
   const code = stringField(source, "code") || stringField(source, "apiCode") || statusCodeToCode(status);
   const rawMessage = stringField(source, "message") || stringField(source, "detail") || fallbackMessage;
-  const message = appendOnboardingHint(
+  const message = code === "eak.delegation.no_allowed_scopes" ? "This AccessKey has no permission scopes. In Qoni Console, open its Permission scope settings, enable the policy needed for this call, then retry." : appendOnboardingHint(
     appendDeniedScopes(appendUpstreamDescription(rawMessage, source), source),
     code
   );
@@ -279,7 +204,7 @@ function errorFromPayload(status, payload, fallbackMessage) {
   if (isDelegationRequired(code)) return new QoniDelegationRequiredError(message, options);
   if (status === 401) return new QoniAuthError(message, options);
   if (status === 403 || isPermissionDenied(code)) {
-    return new QoniPermissionDeniedError(appendKnownScopes(message), options);
+    return new QoniPermissionDeniedError(message, options);
   }
   if (status === 400 || status === 422) return new QoniValidationError(message, options);
   if (status === 429) return new QoniRateLimitError(message, options);
@@ -314,17 +239,14 @@ function appendUpstreamDescription(message, source) {
 }
 var ONBOARDING_HINTS = {
   "eak.delegation.user_not_bound": "Hint: the userId is not in the GenAuth userpool bound to this credential. Resolve a real user with qoni.resolveAnyBoundUser() (demo/smoke) or qoni.currentUser({ accessToken }).",
-  "eak.genauth.userpool_binding_missing": "Hint: bind the Qoni credential to a GenAuth userpool before calling genauth.users.*."
+  "eak.genauth.userpool_binding_missing": "Hint: bind the Qoni credential to a GenAuth userpool before calling genauth.users.*.",
+  "eak.delegation.scope_not_allowed": "Hint: enable the denied scopes in this AccessKey's Permission scope settings in Qoni Console."
 };
 function appendOnboardingHint(message, code) {
   const hint = ONBOARDING_HINTS[code];
   if (!hint || message.includes(hint)) return message;
   return `${message} ${hint}`;
 }
-function appendKnownScopes(message) {
-  if (message.includes("Known scopes:")) return message;
-  return `${message} (Known scopes: ${KNOWN_SCOPES.join(", ")})`;
-}
 function statusCodeToCode(status) {
   if (status === 401) return "auth.failed";
   if (status === 403) return "permission_denied";
@@ -356,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 ---
@@ -486,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"
 };
@@ -548,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) {
@@ -1488,6 +1423,81 @@ function createQoniNamespace(_transport, delegateToken, completeDelegateToken) {
   };
 }
 
+// src/scopes.ts
+var QoniScopes = {
+  GUMEM_SESSION_CREATE: "gumem.session:create",
+  GUMEM_MESSAGE_WRITE: "gumem.message:write",
+  GUMEM_MEMORY_READ: "gumem.memory:read",
+  GUMEM_MEMORY_WRITE: "gumem.memory:write",
+  GUMEM_MEMORY_DELETE: "gumem.memory:delete",
+  GUMEM_SEARCH_RUN: "gumem.search:run",
+  GUMEM_ADMIN_MANAGE: "gumem.admin:manage",
+  GUMEM_RESOURCE_WRITE: "gumem.resource:write",
+  GUMEM_ACTION_WRITE: "gumem.action:write",
+  GUMEM_ACTION_READ: "gumem.action:read",
+  GUMEM_PROFILE_READ: "gumem.profile:read",
+  // WebAgent products: exactly two verbs per product — `read` (observe) and
+  // `manage` (anything that changes execution state). See
+  // wa/docs/qoni-sdk-public-surface.md §3.
+  DO_ANYTHING_READ: "webagent.do_anything:read",
+  DO_ANYTHING_MANAGE: "webagent.do_anything:manage",
+  WEB_SEARCH_READ: "webagent.web_search:read",
+  WEB_SEARCH_MANAGE: "webagent.web_search:manage",
+  DEEP_RESEARCH_READ: "webagent.deep_research:read",
+  DEEP_RESEARCH_MANAGE: "webagent.deep_research:manage",
+  TRACK_READ: "webagent.track:read",
+  TRACK_MANAGE: "webagent.track:manage"
+};
+var QoniProductScopes = {
+  doAnything: [
+    QoniScopes.DO_ANYTHING_READ,
+    QoniScopes.DO_ANYTHING_MANAGE
+  ],
+  webSearch: [
+    QoniScopes.WEB_SEARCH_READ,
+    QoniScopes.WEB_SEARCH_MANAGE
+  ],
+  deepResearch: [
+    QoniScopes.DEEP_RESEARCH_READ,
+    QoniScopes.DEEP_RESEARCH_MANAGE
+  ],
+  track: [
+    QoniScopes.TRACK_READ,
+    QoniScopes.TRACK_MANAGE
+  ]
+};
+var KNOWN_SCOPES = Object.values(QoniScopes);
+var QoniScopeBundles = {
+  GUMEM_READONLY: [QoniScopes.GUMEM_MEMORY_READ, QoniScopes.GUMEM_PROFILE_READ],
+  GUMEM_SESSION_RECALL: [
+    QoniScopes.GUMEM_MEMORY_READ,
+    QoniScopes.GUMEM_MEMORY_WRITE,
+    QoniScopes.GUMEM_MESSAGE_WRITE
+  ],
+  GUMEM_WRITE: [
+    QoniScopes.GUMEM_SESSION_CREATE,
+    QoniScopes.GUMEM_MESSAGE_WRITE,
+    QoniScopes.GUMEM_ACTION_WRITE
+  ],
+  // One bundle per WebAgent product = [read, manage].
+  DO_ANYTHING: [
+    QoniScopes.DO_ANYTHING_READ,
+    QoniScopes.DO_ANYTHING_MANAGE
+  ],
+  WEB_SEARCH: [
+    QoniScopes.WEB_SEARCH_READ,
+    QoniScopes.WEB_SEARCH_MANAGE
+  ],
+  DEEP_RESEARCH: [
+    QoniScopes.DEEP_RESEARCH_READ,
+    QoniScopes.DEEP_RESEARCH_MANAGE
+  ],
+  TRACK: [
+    QoniScopes.TRACK_READ,
+    QoniScopes.TRACK_MANAGE
+  ]
+};
+
 // src/genauth.ts
 function createGenAuthNamespace(transport, options = {}) {
   return {