@qoniai/qoni 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.7.0 - 2026-10-02
+
+### Changed
+
+- `InteractionHandle.openLogin()` now resolves to an `OpenLoginResult`
+  (`{ profileId, siteId, sessionId, liveUrl, raw, confirm() }`) instead of
+  `void`. TypeScript code that stores the method as `() => Promise<void>` needs
+  to widen that type; runtime callers that ignore the result are unaffected.
+
+### Added
+
+- `OpenLoginResult.confirm()` persists the login into the profile
+  (`POST /profiles/{profileId}/confirm`) and reports `active`. Call
+  `confirmSignedIn()` once it is active (or when `probeResult` is
+  `no_session`), otherwise reopen the session with
+  `openLogin({ siteId, profileId })`.
+- `QoniScopes.SITE_LOGIN_REQUEST` (`webagent.site_login:request`) and
+  `QoniScopes.SITE_LOGIN_CONFIRM` (`webagent.site_login:confirm`). They are not
+  part of any product bundle: delegate them explicitly and allow them in the
+  AccessKey policy.
+
+### Fixed
+
+- `openLogin()` now starts a working login session. It sends the `site_id` the
+  backend's `/profiles/login` route requires (the only site listed on the
+  `site_login` interaction, or `openLogin({ siteId })`; pass `profileId` to
+  re-login an existing profile) and requests the site-login scope instead of the
+  product's manage scope. Previously the backend always rejected it. This
+  covers `site_login` interactions on Do Anything and Deep Research runs; Track
+  monitor re-login (`monitor.needs_login`, backend `/track/monitors/{id}/re_auth`)
+  is not wrapped by the SDK yet.
+- `run.wait()` retries a transient failure of the reads it makes after the run
+  finished (run detail, artifact list) up to twice. A dropped connection or a
+  timed-out token exchange no longer fails a run that already succeeded. Only
+  `retryable` errors are retried; aborts and the `timeoutMs` deadline stop it.
+- `track.create()` sends `{ kind: "interval", intervalSeconds }` as
+  `interval_seconds`, as `refine()` already did. The backend previously ignored
+  the camelCase field and fell back to its default 60-second interval. Other
+  schedule fields such as `tz` pass through unchanged, for `create()` and
+  `refine()` alike. Malformed interval or cron schedules are rejected locally.
+- Monitor and tick reads keep user-defined keys verbatim: `extractionSchema`,
+  `baselineExtracted`, a tick's `extracted`, and the `before` / `after` /
+  `added` / `removed` / `sampleUnchanged` values in `diffs` no longer rename
+  `source_url` to `sourceUrl`. Protocol fields are still camelCased.
+
 ## 0.6.0 - 2026-09-23
 
 ### Added

package/README.md

@@ -310,7 +310,7 @@ await qoni.gumem.recall({
 
 ## Choosing Scopes
 
-Each WebAgent product exposes exactly two scopes: `read` (observe — status, events, artifacts) and `manage` (anything that changes execution state — run, cancel, respond, messages, monitor CRUD). The full set is the 8 scopes `webagent.{do_anything, web_search, deep_research, track}:{read, manage}`. The simplest authorization is the `products` sugar — each product name expands to its `read` + `manage` pair:
+Each WebAgent product exposes exactly two scopes: `read` (observe — status, events, artifacts) and `manage` (anything that changes execution state — run, cancel, respond, messages, monitor CRUD). The 8 product scopes are `webagent.{do_anything, web_search, deep_research, track}:{read, manage}`. Interactive site login (`openLogin()`) additionally needs `QoniScopes.SITE_LOGIN_REQUEST` and `QoniScopes.SITE_LOGIN_CONFIRM`, which are not part of any product and must be requested explicitly in `scopes`. The simplest authorization is the `products` sugar — each product name expands to its `read` + `manage` pair:
 
 ```ts
 await qoni.delegateToken({
@@ -457,7 +457,7 @@ const monitor = await qoni.track.create({
 // runNow()/refine() require `active`, so wait for it before acting:
 for await (const event of monitor.events()) {
   if (event.type === "interaction") {
-    const i = monitor.interactionHandle(event.data); // e.g. a needs-reauth site_login
+    const i = monitor.interactionHandle(event.data); // e.g. an intent clarification
     if (i.can("confirm")) await i.confirm();
     continue;
   }
@@ -470,7 +470,9 @@ const ticks = await monitor.runs({ limit: 10 }); // read-only tick run views
 
 // Change the definition with refine() (any subset of: schedule / targetUrls /
 // extractionSchema / triggerDsl / stopConditionDsl / notifyChannel). `schedule`
-// is { kind: "cron", expr } or { kind: "interval", intervalSeconds }. The
+// is { kind: "cron", expr } or { kind: "interval", intervalSeconds } (same for
+// track.create()). Extraction field names and extracted values keep their
+// original keys in get()/run() reads. The
 // natural-language intent isn't refinable — create a new monitor to change it:
 await monitor.refine({ schedule: { kind: "cron", expr: "0 9 * * *" } });
 await monitor.pause();   // stop scheduled ticks without deleting
@@ -623,12 +625,49 @@ for await (const event of run.events()) {
 }
 ```
 
-Methods: `answer(text)`, `skip()`, `confirm()`, `reject()`, `openLogin()`,
+Methods: `answer(text)`, `skip()`, `confirm()`, `reject()`, `openLogin({ siteId?, profileId? })`,
 `confirmSignedIn()`, `connectControl()`, `refreshControl()`, `releaseControl()`,
 `retry()`, `switchProfile()`. `i.can(kind)` reports whether the interaction
 currently offers that action; calling a method the backend did NOT declare
 throws (so a "recovery" button only exists when it actually works).
 
+`openLogin()` starts an interactive login session for a `site_login`
+interaction of a run. Pass `siteId` (one of
+`i.interaction.payload.sites[].siteId`), or omit it when exactly one site is
+listed. Show the returned `liveUrl` to the user; after they sign in, persist the
+login with `login.confirm()`, then tell the agent with `confirmSignedIn()`:
+
+```ts
+import { QoniError } from "@qoniai/qoni";
+
+const login = await i.openLogin();          // { profileId, siteId, sessionId, liveUrl }
+showToUser(login.liveUrl);                  // the user signs in there
+await waitForUserToFinish();
+let result;
+try {
+  result = await login.confirm();           // ends the session; saves the login if found
+} catch (error) {
+  // 409: no pending login for this profile (session already ended, or profile gone).
+  if (!(error instanceof QoniError && error.code === "no_pending_login")) throw error;
+}
+if (!result || result.active || result.probeResult === "no_session") {
+  await i.confirmSignedIn();                // the agent rechecks; it asks again if still signed out
+} else {
+  // The user was not signed in, and confirm() closed that session's browser.
+  const retry = await i.openLogin({ siteId: login.siteId, profileId: login.profileId });
+  showToUser(retry.liveUrl);                // a new session for the same profile
+}
+```
+
+`probeResult: "no_session"` means the backend no longer holds the login session —
+it may already have saved the login on its own once it detected the sign-in, or
+it restarted. Some browser providers instead reject `confirm()` with a
+`QoniError` coded `no_pending_login` (HTTP 409), which the backend also uses when
+the profile no longer exists for this user; the example handles it the same way,
+because the agent rechecks and asks again if the site is still signed out. Delegate
+`QoniScopes.SITE_LOGIN_REQUEST` and `QoniScopes.SITE_LOGIN_CONFIRM`, and allow
+both in the AccessKey policy.
+
 The discriminant strings used above are also exported as constants so you can
 avoid bare literals: `InteractionTypes` (`site_login` / `clarification` /
 `confirmation` / `take_control` / `wait`), `InteractionStatuses`, and
@@ -651,7 +690,7 @@ The 1:1 low-level methods live under `qoni.<product>.api.*` (e.g. `qoni.doAnythi
 
 `event.raw.event` is the **raw wire event type** — an internal transport name (`run.action.started`, `run.section_completed`, …) whose naming is historical and inconsistent, exposed as a plain string. This is an implementation detail, not the product API: developers match on the curated `event.type` above. The full wire-type catalog is intentionally NOT exported — reach for `event.raw.event` (a string) only when you need an exact wire match the curated layer folds into `progress` (e.g. telling a specific browser action apart).
 
-Browser Use and Site Login scopes are reserved until their product runtime SDK methods are exported.
+Browser Use scopes are reserved until their product runtime SDK methods are exported. Site Login scopes (`QoniScopes.SITE_LOGIN_REQUEST`, `QoniScopes.SITE_LOGIN_CONFIRM`) back `InteractionHandle.openLogin()` and `confirm()` on run interactions.
 
 ### Response Shape
 

package/README.zh-CN.md

@@ -281,7 +281,7 @@ await qoni.gumem.recall({
 
 ## Scope 怎么选
 
-每个 WebAgent 产品只有两个 scope：`read`（只读观察——状态、事件、产物）与 `manage`（一切改变执行状态的操作——发起、取消、应答、消息、监控的增删改）。全集共 8 个：`webagent.{do_anything, web_search, deep_research, track}:{read, manage}`。最简单的授权方式是 `products` 糖——每个产品名展开为该产品的 `read` + `manage` 一对：
+每个 WebAgent 产品只有两个 scope：`read`（只读观察——状态、事件、产物）与 `manage`（一切改变执行状态的操作——发起、取消、应答、消息、监控的增删改）。产品 scope 共 8 个：`webagent.{do_anything, web_search, deep_research, track}:{read, manage}`。交互式站点登录（`openLogin()`）另外需要 `QoniScopes.SITE_LOGIN_REQUEST` 和 `QoniScopes.SITE_LOGIN_CONFIRM`，它们不属于任何产品，必须在 `scopes` 中显式申请。最简单的授权方式是 `products` 糖——每个产品名展开为该产品的 `read` + `manage` 一对：
 
 ```ts
 await qoni.delegateToken({
@@ -426,7 +426,7 @@ const monitor = await qoni.track.create({
 // 都要求 `active`，所以先等它就绪再操作：
 for await (const event of monitor.events()) {
   if (event.type === "interaction") {
-    const i = monitor.interactionHandle(event.data); // 如 needs-reauth 的 site_login
+    const i = monitor.interactionHandle(event.data); // 如意图澄清
     if (i.can("confirm")) await i.confirm();
     continue;
   }
@@ -439,7 +439,8 @@ const ticks = await monitor.runs({ limit: 10 }); // tick 产生的 run 只读列
 
 // 用 refine() 改定义（任意字段子集：schedule / targetUrls / extractionSchema /
 // triggerDsl / stopConditionDsl / notifyChannel）。`schedule` 是
-// { kind: "cron", expr } 或 { kind: "interval", intervalSeconds }。
+// { kind: "cron", expr } 或 { kind: "interval", intervalSeconds }（track.create() 相同）。
+// get()/run() 读回时，抽取字段名与抽取结果保留原始键名。
 // 自然语言意图不可 refine——要改描述请新建 monitor：
 await monitor.refine({ schedule: { kind: "cron", expr: "0 9 * * *" } });
 await monitor.pause();   // 停掉定时 tick 但不删除
@@ -568,7 +569,33 @@ for await (const event of run.events()) {
 }
 ```
 
-方法：`answer(text)`、`skip()`、`confirm()`、`reject()`、`openLogin()`、`confirmSignedIn()`、`connectControl()`、`refreshControl()`、`releaseControl()`、`retry()`、`switchProfile()`。`i.can(kind)` 判断该交互当前是否提供这个动作；调用后端没声明的方法会抛错（所以「恢复」按钮只有在真能用时才出现）。
+方法：`answer(text)`、`skip()`、`confirm()`、`reject()`、`openLogin({ siteId?, profileId? })`、`confirmSignedIn()`、`connectControl()`、`refreshControl()`、`releaseControl()`、`retry()`、`switchProfile()`。`i.can(kind)` 判断该交互当前是否提供这个动作；调用后端没声明的方法会抛错（所以「恢复」按钮只有在真能用时才出现）。
+
+`openLogin()` 为运行中的 `site_login` 交互开启一次交互式登录会话。传入 `siteId`（取自 `i.interaction.payload.sites[].siteId`），交互只列出一个站点时可以省略。把返回的 `liveUrl` 展示给用户；用户登录完成后，先用 `login.confirm()` 把登录态写入 Profile，再调用 `confirmSignedIn()` 通知 Agent：
+
+```ts
+import { QoniError } from "@qoniai/qoni";
+
+const login = await i.openLogin();          // { profileId, siteId, sessionId, liveUrl }
+showToUser(login.liveUrl);                  // 用户在这里登录
+await waitForUserToFinish();
+let result;
+try {
+  result = await login.confirm();           // 结束这次会话；检测到登录态就写入 Profile
+} catch (error) {
+  // 409：该 Profile 没有待确认的登录（会话已结束，或 Profile 已不存在）。
+  if (!(error instanceof QoniError && error.code === "no_pending_login")) throw error;
+}
+if (!result || result.active || result.probeResult === "no_session") {
+  await i.confirmSignedIn();                // Agent 重新检查；仍未登录会再次请求
+} else {
+  // 用户没有登录成功，而 confirm() 已关闭这次会话的浏览器。
+  const retry = await i.openLogin({ siteId: login.siteId, profileId: login.profileId });
+  showToUser(retry.liveUrl);                // 同一个 Profile 的新登录会话
+}
+```
+
+`probeResult: "no_session"` 表示服务端已不再持有这次登录会话：它可能在检测到用户登录后已经自动保存了登录态，也可能已经重启。部分浏览器提供方会改为让 `confirm()` 抛出 `code` 为 `no_pending_login` 的 `QoniError`（HTTP 409），服务端在 Profile 已不属于当前用户或已删除时也会返回这个错误码；示例按同样方式处理，因为 Agent 会重新检查，如果站点仍未登录会再次请求。委托时需要申请 `QoniScopes.SITE_LOGIN_REQUEST` 和 `QoniScopes.SITE_LOGIN_CONFIRM`，并在 AccessKey 权限策略中允许这两个 scope。
 
 上面用到的判别字符串也都导出成了常量，避免裸写字面量：`InteractionTypes`（`site_login` / `clarification` / `confirmation` / `take_control` / `wait`）、`InteractionStatuses`、`ActionKinds`（`i.can(...)` 的动作名）。授权 scope 同样有：`QoniScopes`（每个单独 scope）、`QoniProductScopes`（`products` 语法糖展开成的 per-product `read`+`manage` 对）、`QoniScopeBundles`（精选 bundle）。用它们代替手写字符串：
 
@@ -586,7 +613,7 @@ if (i.type === InteractionTypes.Clarification && i.can(ActionKinds.answer)) {
 
 原始 wire 事件类型（`run.action.started` 这种内部传输名，命名是历史遗留、也不一致）**不作为公开导出**——开发者按上面那套精选 `event.type` 匹配即可；极少数要精确 wire 的场景，`event.raw.event` 是个原始字符串，直接比对。
 
-Browser Use、Site Login 的 scope 已预留，但产品运行时 SDK 方法导出前不作为公开方法说明。
+Browser Use 的 scope 已预留，但产品运行时 SDK 方法导出前不作为公开方法说明。Site Login 的 scope（`QoniScopes.SITE_LOGIN_REQUEST`、`QoniScopes.SITE_LOGIN_CONFIRM`）用于运行交互上的 `InteractionHandle.openLogin()` 和 `confirm()`。
 
 ### 返回结构