@qoniai/qoni 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 0.8.0 - Unreleased
+
+### Added
+
+- `qoni.genauth.delegateAgent(input)` returns the grant directly (`grant.token`),
+  or an interactive authorization request, through the existing signed endpoint.
+- `agentKey` is an alias for `agent`. Existing root and `qoni.qoni` entries keep
+  their `QoniResponse` envelopes. Conflicting Agent labels are rejected;
+  the existing top-level `userId` precedence is unchanged.
+
+### Fixed
+
+- Expiry strings such as `"15m"` are converted to integer seconds; valid
+  durations are 60–86400 seconds, matching the GenAuth DTO.
+- Unsupported `deniedScopes` is rejected rather than forwarding an unenforced
+  deny policy. Legacy `mailbox.*`, `web.search`, and `web.extract` scopes are rejected without mapping to product scopes.
+
+### Changed
+
+- Expiry validation now happens locally before signing. Invalid formats and
+  values outside 60–86400 seconds throw `QoniValidationError`; numeric seconds
+  strings are sent as integers.
+
+## 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
@@ -91,8 +159,8 @@ compatible fixes.
 
 ### Changed
 
-- The default Qoni host is now `https://dashboard.qoni.ai` (was
-  `https://anima.eazo.ai/dashboard`). Callers that never passed an explicit `host`
+- The default Qoni host is now `https://dashboard.qoni.ai`.
+  Callers that never passed an explicit `host`
   reach a different control plane after upgrading. Note that the new default has
   no `/dashboard` path segment — pass `host` explicitly for private or local
   deployments.

package/README.md

@@ -251,7 +251,7 @@ Silent product calls receive `token: delegation.data.token`. If that token is an
 
 - **Silent** (`mode: "silent"`, the default) — acts for one end user, so a user
   is **required**: pass `user: { id: <genauthUserId> }` (preferred) or the
-  deprecated top-level `userId`. Omitting it throws `QoniValidationError`
+  top-level `userId`. Omitting it throws `QoniValidationError`
   locally before any request. Authorize with the `products` sugar and/or
   explicit `scopes`.
 - **Interactive** (`mode: "interactive"`) — pass `redirectUri`, `state`,
@@ -306,11 +306,39 @@ await qoni.gumem.recall({
 });
 ```
 
-`completeDelegateToken` is the recommended server callback helper. `delegateAgent` and `completeDelegateAgent` remain as deprecated compatibility names, but the current callback contract is `{ grantId, code, state }`; old `{ code, state }` completion is not supported.
+`completeDelegateToken` is the recommended server callback helper. Root `qoni.delegateAgent` and `qoni.completeDelegateAgent` remain as deprecated compatibility names, but the current callback contract is `{ grantId, code, state }`; old `{ code, state }` completion is not supported.
+
+## Original delegation style (0.8.0, unreleased)
+
+```ts
+const grant = await qoni.genauth.delegateAgent({
+  userId: process.env.QONI_USER_ID!, // The current user's GenAuth ID
+  agentKey: "email-assistant", // Agent audit label; alias for agent
+  scopes: [
+    "webagent.do_anything:read", // Read status, events, and artifacts
+    "webagent.do_anything:manage", // Start/cancel tasks and respond to interactions
+  ],
+  expiresIn: "15m", // Converted to 900 seconds before signing
+});
+console.log(grant.grantId, grant.auditId);
+```
+
+This entry returns the grant directly; root `delegateToken` still returns
+`QoniResponse`, with the token in `response.data.token`. Interactive mode returns
+the authorization request directly; use `completeDelegateToken()` in the server
+callback after consent. `agentKey` aliases `agent`; both labels must agree when
+supplied together. Top-level `userId` retains precedence over `user.id`.
+Expiry accepts integer seconds or whole-number
+`s/m/h/d` durations, between 60 and 86400 seconds. Until published, use the 0.8.0
+source build for these additions.
+
+Legacy `mailbox.*`, `web.search`, and `web.extract` scopes, and `deniedScopes`, are unsupported and rejected.
+They are never expanded into broader product permissions. Product scopes do not
+prohibit email sending or deletion; a prompt is not an enforced deny policy.
 
 ## 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 +485,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 +498,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 +653,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 +718,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

@@ -227,7 +227,7 @@ silent 产品能力方法传入 `token: delegation.data.token`。如果这个 to
 
 **入参形态。** `delegateToken` 用 `mode` 判别：
 
-- **Silent**（`mode: "silent"`，默认）——代表某个终端用户,所以 user **必填**：传 `user: { id: <genauthUserId> }`（推荐）或已废弃的顶层 `userId`。不传会在请求发出前本地抛 `QoniValidationError`。授权用 `products` 语法糖和/或显式 `scopes`。
+- **Silent**（`mode: "silent"`，默认）——代表某个终端用户,所以 user **必填**：传 `user: { id: <genauthUserId> }`（推荐）或顶层 `userId`。不传会在请求发出前本地抛 `QoniValidationError`。授权用 `products` 语法糖和/或显式 `scopes`。
 - **Interactive**（`mode: "interactive"`）——传 `redirectUri`、`state`、`agent`、`scopes`，**不传** user（Qoni Console 在授权时解析登录）。返回 `data.authorizationUrl` 而非 token；在服务端用 `completeDelegateToken({ grantId, code, state })` 完成。
 
 `agent` 可选，默认 `"sdk"`。
@@ -277,11 +277,36 @@ await qoni.gumem.recall({
 });
 ```
 
-`completeDelegateToken` 是推荐的服务端 callback helper。`delegateAgent` 和 `completeDelegateAgent` 仍保留为 deprecated 兼容命名，但当前 callback 契约是 `{ grantId, code, state }`；旧的 `{ code, state }` complete 签名不再兼容。
+`completeDelegateToken` 是推荐的服务端 callback helper。顶层 `qoni.delegateAgent` 和 `qoni.completeDelegateAgent` 仍保留为 deprecated 兼容命名，但当前 callback 契约是 `{ grantId, code, state }`；旧的 `{ code, state }` complete 签名不再兼容。
+
+## 原始委托写法（0.8.0，尚未发布）
+
+```ts
+const grant = await qoni.genauth.delegateAgent({
+  userId: process.env.QONI_USER_ID!, // 当前用户的 GenAuth ID
+  agentKey: "email-assistant", // Agent 审计标签，兼容 agent 参数
+  scopes: [
+    "webagent.do_anything:read", // 读取任务状态、事件和产物
+    "webagent.do_anything:manage", // 启动、取消任务和提交交互响应
+  ],
+  expiresIn: "15m", // 签名前转换为 900 秒
+});
+console.log(grant.grantId, grant.auditId);
+```
+
+此入口直接返回 grant；顶层 `delegateToken` 仍返回 `QoniResponse`，token 在
+`response.data.token` 中。交互式模式直接返回授权请求；用户同意后，在服务端回调
+用 `completeDelegateToken()` 兑换 token。`agentKey`、`userId` 分别兼容 `agent`、
+`user.id`；同时提供两个 Agent 标签时必须一致，顶层 `userId` 保持原有的优先级。
+有效期支持整数秒或整数 `s/m/h/d` 时长，
+范围为 60–86400 秒。这些新增能力在发布前需要使用 0.8.0 源码构建。
+
+旧版 `mailbox.*`、`web.search`、`web.extract` scope 和 `deniedScopes` 不受支持，SDK 会拒绝，不会将它们
+扩展成更宽的产品权限。产品 scope 不限制发送、删除邮件；任务描述不能代替禁止策略。
 
 ## 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 +451,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 +464,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 +594,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 +638,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()`。
 
 ### 返回结构