@qoniai/qoni 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,6 +1,106 @@
 # Changelog
 
-## 0.8.0 - Unreleased
+## 0.9.0 - 2026-10-07
+
+DoAnything interactions are now typed by what the user has to do, never by
+business: `site_login`, `take_control`, `ask_user`, `confirmation`, plus the
+system `wait`.
+
+### Changed
+
+- `Interaction` is a union distributed over `type`: `switch (interaction.type)`
+  narrows `payload` in each branch, including `handle.interaction` inside
+  `onInteraction`. `Interaction<"site_login">` still picks one member.
+  `TypedInteraction` names the union. Because it is now a type alias, not an
+  interface, `interface X extends Interaction` no longer compiles (TS2312):
+  use `type X = Interaction & { ... }`. Code that builds an `Interaction` from a
+  separate `type` and `payload` must narrow them together or cast the object.
+- The wire's `clarification` is presented as `ask_user`, with payload
+  `{ question, answerType, options? }`. `answerType` is `text`, `number`,
+  `boolean`, `single_choice` or `multiple_choice`, and options are
+  `{ value, label }`. A clarification with choices becomes `single_choice`; one
+  without choices is `text`. A native `ask_user` keeps the `answer_type` it
+  sends, and every string option value is kept, including `""`.
+  Migration: compare `type` with `"ask_user"` instead of `"clarification"`
+  (TypeScript no longer compiles the old comparison); read
+  `payload.answerType` / `payload.options` instead of `payload.inputType`
+  (removed) or the answer action's `inputSchema` enum.
+  `InteractionTypes.Clarification` is deprecated and now equals
+  `InteractionTypes.AskUser`: it still matches interactions the SDK hands out,
+  but not a raw wire `type` or a `"clarification"` string you stored.
+  `ClarificationPayload` is a deprecated alias of `AskUserPayload`, which
+  requires `answerType`.
+- `InteractionHandle.answer(value)` accepts the structured value its
+  `answerType` names (string, number, boolean, one option value, or an array of
+  option values) and throws `QoniValidationError` before sending a value that
+  does not fit.
+- `InteractionHandle.confirmSignedIn()` saves the login opened by `openLogin()`
+  on the same interaction (`POST /profiles/{profileId}/confirm`, scope
+  `webagent.site_login:confirm`), then tells the agent to recheck. Sign-in is
+  `openLogin()` → `confirmSignedIn()`:
+  - It saves once and rechecks once per login session, however many handles
+    or concurrent calls ask; the deprecated `OpenLoginResult.confirm()` shares
+    the same save.
+  - A user who is not signed in yet, or 409 `no_pending_login`, still gets a
+    recheck: the agent raises a new `site_login` when needed.
+  - When the backend keeps the session but could not save it
+    (`probeResult: "release_failed"`), it throws a retryable `QoniError` coded
+    `site_login.save_failed` and does not tell the agent to go on; calling it
+    again saves again. Any other save failure is thrown as well.
+  - When `openLogin()` calls overlap, the latest call that succeeds owns the
+    session, whichever response arrives last.
+  - Reopening that returns the same backend session shares its save; when a
+    newer backend session replaces it, `confirm()` on the old result throws
+    `QoniValidationError` instead of saving. If the login is reopened while a
+    `confirmSignedIn()` is still saving, that call throws a retryable
+    `QoniError` coded `site_login.session_replaced` without telling the agent
+    to go on; call it again to save the newer login.
+  - Handles from the same `RunHandle` or `MonitorHandle` share the login
+    session, so a handle from a later callback saves it too. A RunHandle from
+    another `attach()` or process does not.
+- `connectControl()` and `refreshControl()` resolve to a `ControlSession`
+  (`{ liveUrl, expiresAt?, status?, raw }`, the signed URL of the browser the
+  user now controls) instead of `void`. `await handle.connectControl()` is
+  unaffected; code that returns the call where `Promise<void>` is expected,
+  such as `const cb: () => Promise<void> = () => handle.connectControl()`, no
+  longer compiles (TS2322) — wrap it: `async () => { await handle.connectControl(); }`.
+- `run.events()`, `wait({ onInteraction })` and `monitor.events()` keep an
+  interaction's type and content when the backend settles it with an empty
+  shell (a resolve labelled `clarification` with an empty question, or a
+  `site_login` with one empty site): only `status`, `resolvedAt` and `actions`
+  change. A settled update with content of its own, such as an expired
+  take-over with its reason, replaces the card as before. Run and monitor
+  handles keep about 256 interactions, forgetting settled cards first, and
+  logins once they are saved or their interaction ended; a pending card or a
+  login still in progress is never dropped.
+
+### Added
+
+- `QoniScopes.USER_PROFILE_READ` (`user.profile:read`), `USER_PROFILE_WRITE`
+  (`user.profile:write`), `USER_PAYMENT_USE` (`user.payment:use`),
+  `AGENT_MAIL_READ` (`agent.mail:read`) and `AGENT_MAIL_SEND`
+  (`agent.mail:send`). They belong to no product bundle: request them
+  explicitly, and allow them in the AccessKey policy. The constants only name
+  the scopes; requesting them does not by itself enable Profile, payment or
+  mailbox access in a run.
+- Exported types `AskUserPayload`, `AskUserOption`, `AskUserAnswer`,
+  `AskUserAnswerType`, `InteractionBase`, `TypedInteraction` and
+  `ControlSession`.
+
+### Fixed
+
+- A scope written without its service prefix names every matching scope:
+  `profile:read` suggests both `gumem.profile:read` and `user.profile:read`.
+
+### Deprecated
+
+- `user` / `userId` on interactive delegation input: the authorization page
+  identifies the signed-in user, and the delegation service ignores them.
+- `DelegateTokenResponse.grantedScopes`: the delegation service does not return
+  it. Read `qoni.genauth.introspectDelegationToken({ token }).data.scope`.
+- `OpenLoginResult.confirm()`: `confirmSignedIn()` saves the login itself.
+
+## 0.8.0 - 2026-10-04
 
 ### Added
 
@@ -150,7 +250,7 @@ compatible fixes.
 - Optional abort signals on product run-detail and artifact-list wire reads;
   existing calls without a signal remain compatible.
 
-## Unreleased
+## Earlier changes
 
 ### Breaking
 

package/README.md

@@ -151,7 +151,7 @@ const run = await qoni.doAnything.run({
 
 const result = await run.wait({
   onScreenshot: (img, i) => fs.writeFileSync(`step-${i}.jpg`, img.bytes),
-  onInteraction: (i) => {                 // login / clarify / confirm / take-control
+  onInteraction: (i) => {                 // site_login / take_control / ask_user / confirmation
     if (i.can("confirm_signed_in")) return i.confirmSignedIn();
     if (i.can("confirm")) return i.confirm();
   },
@@ -286,18 +286,27 @@ const grant = await qoni.delegateToken({
   scopes: ["gumem.memory:read", "webagent.do_anything:manage"],
 });
 
+// The callback will not carry grantId: save it with your business state, keyed by grantState.
+await savePendingGrant(grant.data.grantState, {
+  grantId: grant.data.grantId,
+  businessState: "business-csrf-state",
+});
 redirectUserTo(grant.data.authorizationUrl);
 ```
 
-The user visits `authorizationUrl` in Qoni Console/BFF. If they are not logged in, Console/BFF sends them through GenAuth login, confirms authorization, completes the grant internally, then redirects back to your `redirectUri` with a one-time `code`, your `state`, and `grant_state`/`grantId`. The browser never receives a delegation token.
+The user visits `authorizationUrl` in Qoni Console/BFF. If they are not logged in, Console/BFF sends them through GenAuth login, confirms authorization, completes the grant internally, then redirects back to your `redirectUri` with a one-time `code`, your `state`, and `grant_state`. The callback does **not** carry `grantId`, so look up the record you saved by `grant_state`. The browser never receives a delegation token.
 
 Your callback handler runs on the server and exchanges the callback fields with AK/SK:
 
 ```ts
+const pending = await loadPendingGrant(String(req.query.grant_state));
+// Your business state comes back unchanged; reject forged or mixed-up callbacks.
+if (!pending || req.query.state !== pending.businessState) throw new Error("Invalid delegation callback");
+
 const completed = await qoni.completeDelegateToken({
-  grantId: String(req.query.grantId ?? req.query.grant_id),
+  grantId: pending.grantId,
   code: String(req.query.code),
-  state: String(req.query.state),
+  state: String(req.query.grant_state), // grant_state, not your business state
 });
 
 await qoni.gumem.recall({
@@ -308,7 +317,7 @@ await qoni.gumem.recall({
 
 `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)
+## Original delegation style (0.8.0+)
 
 ```ts
 const grant = await qoni.genauth.delegateAgent({
@@ -329,8 +338,8 @@ 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.
+`s/m/h/d` durations, between 60 and 86400 seconds. These additions are available
+in the published `@qoniai/qoni@0.8.0` release.
 
 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
@@ -348,7 +357,9 @@ await qoni.delegateToken({
 });
 ```
 
-Scope strings are validated locally before any request: a scope missing its service prefix (e.g. `do_anything:manage` instead of `webagent.do_anything:manage`) throws `QoniValidationError` immediately with the correct form in the message.
+Scope strings are validated locally before any request: a scope missing its service prefix (e.g. `do_anything:manage` instead of `webagent.do_anything:manage`) throws `QoniValidationError` immediately with the correct form in the message — every candidate when the short form is ambiguous (`profile:read` → `gumem.profile:read` or `user.profile:read`).
+
+The site-login, user Profile, payment and Agent mailbox scopes (`QoniScopes.SITE_LOGIN_*`, `USER_PROFILE_READ`, `USER_PROFILE_WRITE`, `USER_PAYMENT_USE`, `AGENT_MAIL_READ`, `AGENT_MAIL_SEND`) belong to no product: request them explicitly in `scopes`, and allow them in the AccessKey policy. The user Profile, payment and Agent mailbox constants only name the scopes; requesting them does not by itself enable Profile, payment or mailbox access in a run.
 
 Use explicit scope strings when the requested permission boundary should be visible in code.
 
@@ -360,6 +371,10 @@ Use explicit scope strings when the requested permission boundary should be visi
 | Search public web | `webagent.web_search:read`, `webagent.web_search:manage` | Agent can search public pages and read search results. |
 | Run a bounded web task | `webagent.do_anything:read`, `webagent.do_anything:manage` | Agent can run a visible web task, read progress, stop it, and intervene when needed. |
 | Create a monitor | `webagent.track:read`, `webagent.track:manage` | Agent can configure monitors, read events, run checks, and stop monitors. |
+| Sign in to sites during a run | `webagent.site_login:request`, `webagent.site_login:confirm` | The user signs in through a live browser; the login is saved for later tasks. |
+| Use the user's Profile | `user.profile:read`, `user.profile:write` | Agent can read the user's saved details (name, phone, shipping address, card brand and last 4) and save new ones the user provides. |
+| Pay with the user's saved card | `user.payment:use` | After the user approves a payment, the saved card is filled in for them. |
+| Use the Agent's own mailbox | `agent.mail:read`, `agent.mail:send` | Agent can read mail sent to its own address (such as verification codes) and send mail from it. |
 
 Silent mode is usually appropriate for low-risk actions such as reading current-user memory, writing a confirmed summary, or searching public web pages.
 
@@ -634,81 +649,113 @@ the backend contract.
 
 ### Interactions (HITL)
 
-When a run needs the user — sign in to a site, answer a clarification, approve a
-plan, take over the browser, or wait — it emits an `interaction` event whose
-`event.data` is a typed `Interaction` (discriminated by `type`: `site_login` /
-`clarification` / `confirmation` / `take_control` / `wait`). Wrap it in a handle
-and call the action methods; each posts to the endpoint the backend declared in
-the interaction's `actions[]`, so you never hard-code a route:
+When a run needs the user, it pauses and emits an `interaction` event whose
+`event.data` is a typed `Interaction`. Interactions are typed by what the user
+has to do, never by business, so one handler covers every task:
 
-```ts
-for await (const event of run.events()) {
-  if (event.type === "interaction") {
-    const i = run.interactionHandle(event.data);   // event.data is the Interaction
-    if (i.type === "clarification" && i.can("answer")) await i.answer("the blue button");
-    else if (i.can("confirm")) await i.confirm();
-    else if (i.can("confirm_signed_in")) await i.confirmSignedIn();
-    else if (i.can("release_control")) await i.releaseControl();
-  }
-}
-```
-
-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).
+| `type` | The user… | Methods |
+| --- | --- | --- |
+| `site_login` | signs in to a site in the live browser | `openLogin()`, `confirmSignedIn()` |
+| `take_control` | operates the browser by hand (captcha, 2FA, …) | `connectControl()`, `refreshControl()`, `releaseControl()` |
+| `ask_user` | answers a question shaped by `answerType` / `options` | `answer()`, `skip()` |
+| `confirmation` | allows or rejects an action | `confirm()`, `reject()` |
+| `wait` | nothing — the system is waiting (rate limit, external event) | `retry()` |
 
-`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()`:
+`Interaction` is a union distributed over `type`, so `switch (request.type)`
+narrows `request.payload` in each branch. Each method posts to the endpoint the
+backend declared in the interaction's `actions[]`, so you never hard-code a route:
 
 ```ts
-import { QoniError } from "@qoniai/qoni";
+import type { InteractionHandle } 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
+const handled = new Set<string>();
+
+async function handleInteraction(handle: InteractionHandle) {
+  const request = handle.interaction;
+  // Creation, status updates and replays all call back: act once per pending id.
+  if (request.status !== "pending" || handled.has(request.id)) return;
+  handled.add(request.id);
+
+  switch (request.type) {
+    case "site_login": {
+      const login = await handle.openLogin();   // { liveUrl, ... } of a live login browser
+      await showToUser(login.liveUrl);          // resolves when the user clicks "I'm signed in"
+      await handle.confirmSignedIn();           // saves the login, then the agent rechecks and continues
+      break;
+    }
+    case "take_control": {
+      // connectControl() resolves to the signed control URL, when the backend offers it
+      const control = handle.can("connect_control") ? await handle.connectControl() : undefined;
+      await showToUser(control?.liveUrl ?? request.payload.liveUrl);
+      await handle.releaseControl();            // hand the browser back
+      break;
+    }
+    case "ask_user":                            // payload: { question, answerType, options? }
+      await handle.answer(await askUser(request.payload));
+      break;
+    case "confirmation":                        // payload: { summary }
+      if (await approve(request.payload.summary)) await handle.confirm();
+      else await handle.reject();
+      break;
+  }
 }
-```
 
-`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
+const result = await run.wait({ onInteraction: handleInteraction });
+```
+
+Interactions arrive one at a time: the run waits until the current one is
+handled. The same interaction calls back again on every status change and on
+reconnect replays, always with the same `id` and `type` — key your UI cards by
+`request.id`. An update with content of its own replaces the card (a take-over
+that became `active` carries its new `liveUrl`); when the backend settles an
+interaction with an empty shell, the card keeps its original `payload`. A
+`take_control` that arrives already `active` was started by the user, for
+example from Console; show it if your UI offers control there. Methods: `answer(value)`, `skip()`, `confirm()`,
+`reject()`, `openLogin({ siteId?, profileId? })`, `confirmSignedIn()`,
+`connectControl()`, `refreshControl()`, `releaseControl()`, `retry()`,
+`switchProfile()`. `connectControl()` and `refreshControl()` resolve to
+`{ liveUrl, expiresAt?, status?, raw }`: the signed URL of the browser the user
+now controls. `handle.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).
+
+**`ask_user` answers are structured.** `answer()` takes the value matching
+`payload.answerType` — `text` → string, `number` → number, `boolean` → boolean,
+`single_choice` → one `options[].value`, `multiple_choice` → an array of option
+values — and throws `QoniValidationError` before sending anything that does not
+fit. The wire still calls this type `clarification`; the SDK presents it as
+`ask_user` (choices arrive as `{ value, label }` options).
+
+**Sign-in takes two calls.** `openLogin()` opens a live login browser for the
+`site_login` interaction (pass `siteId` from `payload.sites[].siteId`, or omit it
+when exactly one site is listed). Once the user is signed in, `confirmSignedIn()`
+saves the login so later tasks reuse it, then tells the agent to recheck the site
+and continue; if the user turns out not to be signed in, the agent raises a new
+`site_login`. It saves once and rechecks once per login session, however many
+times it is called. If the backend could not save the login yet, it throws a
+retryable `QoniError` coded `site_login.save_failed` without telling the agent to
+go on; call it again. The same holds for `site_login.session_replaced`, thrown
+when the login was reopened while it was being saved. Handles from the same `RunHandle` (or `MonitorHandle`)
+share the login session, so `confirmSignedIn()` also works on the handle of a
+later callback; a RunHandle from a new `attach()` does not. 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
-`ActionKinds` (the `i.can(...)` action names). Authorization scope strings have
-the same treatment — `QoniScopes` (every individual scope), `QoniProductScopes`
-(the per-product `read`+`manage` pairs the `products` sugar expands to), and
-`QoniScopeBundles` (curated bundles). Use them in place of hand-typed strings:
+both in the AccessKey policy. `openLogin()`'s result still offers `confirm()` for
+callers that save the login themselves; it is deprecated.
+
+The discriminant strings are also exported as constants so you can avoid bare
+literals: `InteractionTypes` (`SiteLogin` / `TakeControl` / `AskUser` /
+`Confirmation` / `Wait`; the deprecated `Clarification` now equals `AskUser`),
+`InteractionStatuses`, and `ActionKinds` (the `handle.can(...)` action names).
+Authorization scope strings have the same treatment — `QoniScopes` (every
+individual scope), `QoniProductScopes` (the per-product `read`+`manage` pairs the
+`products` sugar expands to), and `QoniScopeBundles` (curated bundles). Use them in
+place of hand-typed strings:
 
 ```ts
 import { InteractionTypes, ActionKinds, QoniScopes } from "@qoniai/qoni";
 
-if (i.type === InteractionTypes.Clarification && i.can(ActionKinds.answer)) {
-  await i.answer("the blue button");
+if (handle.type === InteractionTypes.AskUser && handle.can(ActionKinds.answer)) {
+  await handle.answer("the blue button");
 }
 ```
 
@@ -718,7 +765,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 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.
+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 `confirmSignedIn()` on run interactions.
 
 ### Response Shape
 

package/README.zh-CN.md

@@ -144,7 +144,7 @@ const run = await qoni.doAnything.run({
 
 const result = await run.wait({
   onScreenshot: (img, i) => fs.writeFileSync(`step-${i}.jpg`, img.bytes),
-  onInteraction: (i) => {                 // 登录 / 澄清 / 确认 / 接管
+  onInteraction: (i) => {                 // site_login / take_control / ask_user / confirmation
     if (i.can("confirm_signed_in")) return i.confirmSignedIn();
     if (i.can("confirm")) return i.confirm();
   },
@@ -257,18 +257,27 @@ const grant = await qoni.delegateToken({
   scopes: ["gumem.memory:read", "webagent.do_anything:manage"],
 });
 
+// 回调不会带回 grantId：按 grantState 保存 grantId 和业务 state
+await savePendingGrant(grant.data.grantState, {
+  grantId: grant.data.grantId,
+  businessState: "business-csrf-state",
+});
 redirectUserTo(grant.data.authorizationUrl);
 ```
 
-用户访问 `authorizationUrl` 进入 Qoni Console/BFF。若用户未登录，Console/BFF 会先走 GenAuth 登录；授权确认后由 Console/BFF 统一 complete，再回跳业务 `redirectUri`，只带一次性 `code`、业务 `state`、`grant_state`/`grantId`。浏览器不会拿到 delegation token。
+用户访问 `authorizationUrl` 进入 Qoni Console/BFF。若用户未登录，Console/BFF 会先走 GenAuth 登录；授权确认后由 Console/BFF 统一 complete，再回跳业务 `redirectUri`，只带一次性 `code`、业务 `state` 和 `grant_state`，**不带 `grantId`**，需要按 `grant_state` 找回创建请求时保存的记录。浏览器不会拿到 delegation token。
 
 业务 callback handler 在服务端用 AK/SK 兑换最终 token：
 
 ```ts
+const pending = await loadPendingGrant(String(req.query.grant_state));
+// 业务 state 原样回到回调里，和保存的值比对，防止回调被伪造或串用
+if (!pending || req.query.state !== pending.businessState) throw new Error("Invalid delegation callback");
+
 const completed = await qoni.completeDelegateToken({
-  grantId: String(req.query.grantId ?? req.query.grant_id),
+  grantId: pending.grantId,
   code: String(req.query.code),
-  state: String(req.query.state),
+  state: String(req.query.grant_state), // 传 grant_state，不是业务 state
 });
 
 await qoni.gumem.recall({
@@ -279,7 +288,7 @@ await qoni.gumem.recall({
 
 `completeDelegateToken` 是推荐的服务端 callback helper。顶层 `qoni.delegateAgent` 和 `qoni.completeDelegateAgent` 仍保留为 deprecated 兼容命名，但当前 callback 契约是 `{ grantId, code, state }`；旧的 `{ code, state }` complete 签名不再兼容。
 
-## 原始委托写法（0.8.0，尚未发布）
+## 原始委托写法（0.8.0 起）
 
 ```ts
 const grant = await qoni.genauth.delegateAgent({
@@ -299,7 +308,7 @@ console.log(grant.grantId, grant.auditId);
 用 `completeDelegateToken()` 兑换 token。`agentKey`、`userId` 分别兼容 `agent`、
 `user.id`；同时提供两个 Agent 标签时必须一致，顶层 `userId` 保持原有的优先级。
 有效期支持整数秒或整数 `s/m/h/d` 时长，
-范围为 60–86400 秒。这些新增能力在发布前需要使用 0.8.0 源码构建。
+范围为 60–86400 秒。这些新增能力已随 `@qoniai/qoni@0.8.0` 发布到 npm。
 
 旧版 `mailbox.*`、`web.search`、`web.extract` scope 和 `deniedScopes` 不受支持，SDK 会拒绝，不会将它们
 扩展成更宽的产品权限。产品 scope 不限制发送、删除邮件；任务描述不能代替禁止策略。
@@ -316,7 +325,9 @@ await qoni.delegateToken({
 });
 ```
 
-scope 字符串在发请求前就会本地预检：漏掉服务前缀（比如写成 `do_anything:manage` 而不是 `webagent.do_anything:manage`）会立即抛出 `QoniValidationError`，错误消息里带正确写法。
+scope 字符串在发请求前就会本地预检：漏掉服务前缀（比如写成 `do_anything:manage` 而不是 `webagent.do_anything:manage`）会立即抛出 `QoniValidationError`，错误消息里带正确写法；短写法有歧义时列出全部候选（`profile:read` → `gumem.profile:read` 或 `user.profile:read`）。
+
+站点登录、用户 Profile、支付和 Agent 邮箱的 scope（`QoniScopes.SITE_LOGIN_*`、`USER_PROFILE_READ`、`USER_PROFILE_WRITE`、`USER_PAYMENT_USE`、`AGENT_MAIL_READ`、`AGENT_MAIL_SEND`）不属于任何产品：需要在 `scopes` 中显式申请，并在 AccessKey 权限策略中允许。用户 Profile、支付和 Agent 邮箱这几个常量只是 scope 名称：申请它们本身不会让任务获得 Profile、支付或邮箱能力。
 
 需要让授权边界直接出现在业务代码里时，使用显式 scope 字符串。
 
@@ -328,6 +339,10 @@ scope 字符串在发请求前就会本地预检：漏掉服务前缀（比如
 | 搜索公开网页 | `webagent.web_search:read`, `webagent.web_search:manage` | Agent 可以搜索公开网页并读取结果。 |
 | 执行网页任务 | `webagent.do_anything:read`, `webagent.do_anything:manage` | Agent 可以执行有边界的网页任务、读取进度、停止任务，并在需要时介入控制。 |
 | 创建长期监控 | `webagent.track:read`, `webagent.track:manage` | Agent 可以配置监控、读取事件、立即运行检查，并停止监控。 |
+| 在任务中登录网站 | `webagent.site_login:request`, `webagent.site_login:confirm` | 用户在实时浏览器里亲自登录，登录状态保存后供之后的任务复用。 |
+| 使用用户 Profile | `user.profile:read`, `user.profile:write` | Agent 可以读取用户保存的资料（姓名、手机号、收货地址、卡组织和后四位），并保存用户新提供的资料。 |
+| 用用户保存的卡支付 | `user.payment:use` | 用户允许一笔支付后，替用户填入已保存的信用卡。 |
+| 使用 Agent 自己的邮箱 | `agent.mail:read`, `agent.mail:send` | Agent 可以读取发到自己邮箱的邮件（例如验证码），并用它发送邮件。 |
 
 低风险能力通常可以静默授权，例如读取当前用户自己的 GUMem、写入本次会话摘要、搜索公开网页、读取普通任务结果。
 
@@ -580,55 +595,69 @@ interface RunResult {
 
 ### 交互（HITL）
 
-当 run 需要用户参与——登录某站、回答澄清、审批计划、接管浏览器、或等待——会发出一个 `interaction` 事件，`event.data` 是带类型的 `Interaction`（用 `type` 判别：`site_login` / `clarification` / `confirmation` / `take_control` / `wait`）。把它包成句柄再调动作方法即可；每个方法会 POST 到交互 `actions[]` 里后端声明的 endpoint，不需要写死路由：
+run 需要用户出手时会暂停，并发出一个 `interaction` 事件，`event.data` 是带类型的 `Interaction`。交互按「需要用户做什么」分类，和具体业务无关，所以一个处理函数就能覆盖所有任务：
 
-```ts
-for await (const event of run.events()) {
-  if (event.type === "interaction") {
-    const i = run.interactionHandle(event.data);   // event.data 就是 Interaction
-    if (i.type === "clarification" && i.can("answer")) await i.answer("蓝色那个按钮");
-    else if (i.can("confirm")) await i.confirm();
-    else if (i.can("confirm_signed_in")) await i.confirmSignedIn();
-    else if (i.can("release_control")) await i.releaseControl();
-  }
-}
-```
-
-方法：`answer(text)`、`skip()`、`confirm()`、`reject()`、`openLogin({ siteId?, profileId? })`、`confirmSignedIn()`、`connectControl()`、`refreshControl()`、`releaseControl()`、`retry()`、`switchProfile()`。`i.can(kind)` 判断该交互当前是否提供这个动作；调用后端没声明的方法会抛错（所以「恢复」按钮只有在真能用时才出现）。
+| `type` | 用户要做的事 | 方法 |
+| --- | --- | --- |
+| `site_login` | 在实时浏览器里亲自登录某个网站 | `openLogin()`、`confirmSignedIn()` |
+| `take_control` | 亲手操作浏览器（验证码、两步验证等） | `connectControl()`、`refreshControl()`、`releaseControl()` |
+| `ask_user` | 回答一个问题，答案结构由 `answerType` / `options` 描述 | `answer()`、`skip()` |
+| `confirmation` | 允许或拒绝一个操作 | `confirm()`、`reject()` |
+| `wait` | 不需要做决定：系统在等待（限流、外部事件） | `retry()` |
 
-`openLogin()` 为运行中的 `site_login` 交互开启一次交互式登录会话。传入 `siteId`（取自 `i.interaction.payload.sites[].siteId`），交互只列出一个站点时可以省略。把返回的 `liveUrl` 展示给用户；用户登录完成后，先用 `login.confirm()` 把登录态写入 Profile，再调用 `confirmSignedIn()` 通知 Agent：
+`Interaction` 是按 `type` 分布的联合类型，`switch (request.type)` 之后每个分支里的 `request.payload` 会自动收窄。每个方法都 POST 到交互 `actions[]` 里后端声明的 endpoint，不需要写死路由：
 
 ```ts
-import { QoniError } from "@qoniai/qoni";
+import type { InteractionHandle } 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 的新登录会话
+const handled = new Set<string>();
+
+async function handleInteraction(handle: InteractionHandle) {
+  const request = handle.interaction;
+  // 创建、状态更新和断线回放都会回调：每个待处理的交互只处理一次
+  if (request.status !== "pending" || handled.has(request.id)) return;
+  handled.add(request.id);
+
+  switch (request.type) {
+    case "site_login": {
+      const login = await handle.openLogin();   // 打开受控登录浏览器，返回实时画面 login.liveUrl
+      await showToUser(login.liveUrl);          // 用户点「我已登录」后返回
+      await handle.confirmSignedIn();           // 保存登录状态，Agent 复查后继续
+      break;
+    }
+    case "take_control": {
+      // 服务端提供开始接管时，connectControl() 返回签名后的控制地址
+      const control = handle.can("connect_control") ? await handle.connectControl() : undefined;
+      await showToUser(control?.liveUrl ?? request.payload.liveUrl);
+      await handle.releaseControl();            // 把浏览器交还给 Agent
+      break;
+    }
+    case "ask_user":                            // payload：{ question, answerType, options? }
+      await handle.answer(await askUser(request.payload));
+      break;
+    case "confirmation":                        // payload：{ summary }
+      if (await approve(request.payload.summary)) await handle.confirm();
+      else await handle.reject();
+      break;
+  }
 }
+
+const result = await run.wait({ onInteraction: handleInteraction });
 ```
 
-`probeResult: "no_session"` 表示服务端已不再持有这次登录会话：它可能在检测到用户登录后已经自动保存了登录态，也可能已经重启。部分浏览器提供方会改为让 `confirm()` 抛出 `code` 为 `no_pending_login` 的 `QoniError`（HTTP 409），服务端在 Profile 已不属于当前用户或已删除时也会返回这个错误码；示例按同样方式处理，因为 Agent 会重新检查，如果站点仍未登录会再次请求。委托时需要申请 `QoniScopes.SITE_LOGIN_REQUEST` 和 `QoniScopes.SITE_LOGIN_CONFIRM`，并在 AccessKey 权限策略中允许这两个 scope。
+交互按顺序一个一个出现：当前这个处理完，run 才会继续。同一个交互在每次状态变化和断线回放时都会再次回调，`id` 和 `type` 始终不变——界面卡片请按 `request.id` 更新。带有新内容的更新会替换卡片（例如接管变成 `active` 时带来新的 `liveUrl`）；后端用空壳结束交互时，卡片保留原来的 `payload`。直接以 `active` 出现的 `take_control` 是用户自己发起的接管（例如在 Console 里），界面提供接管入口时再展示它。方法：`answer(value)`、`skip()`、`confirm()`、`reject()`、`openLogin({ siteId?, profileId? })`、`confirmSignedIn()`、`connectControl()`、`refreshControl()`、`releaseControl()`、`retry()`、`switchProfile()`。`connectControl()` 和 `refreshControl()` 返回 `{ liveUrl, expiresAt?, status?, raw }`：用户正在控制的那个浏览器的签名地址。`handle.can(kind)` 判断该交互当前是否提供这个动作；调用后端没声明的方法会抛错（所以「恢复」按钮只有在真能用时才出现）。
+
+**`ask_user` 的回答是结构化的。** `answer()` 接收与 `payload.answerType` 对应的值：`text` → 字符串，`number` → 数字，`boolean` → 布尔，`single_choice` → 一个 `options[].value`，`multiple_choice` → 选项 value 数组；不匹配时在发送前就抛出 `QoniValidationError`。线上协议里这个类型仍叫 `clarification`，SDK 统一呈现为 `ask_user`（候选项是 `{ value, label }`）。
+
+**登录只需两步。** `openLogin()` 为 `site_login` 交互打开一个实时登录浏览器（`siteId` 取自 `payload.sites[].siteId`，只列出一个站点时可以省略）。用户登录完成后调用 `confirmSignedIn()`：SDK 先保存这次登录，之后的任务直接复用，再通知 Agent 复查站点并继续；如果用户其实没有登录成功，Agent 会再发起一次 `site_login`。无论调用几次，同一个登录会话只保存一次、只通知 Agent 复查一次。后端暂时没能保存登录时，它抛出 `code` 为 `site_login.save_failed` 的可重试 `QoniError`，不会让 Agent 继续；再调用一次即可。保存期间用户又重开了登录时，抛出的是 `site_login.session_replaced`，处理方式相同。同一个 `RunHandle`（或 `MonitorHandle`）发出的句柄共享登录会话，所以在之后回调拿到的句柄上调用 `confirmSignedIn()` 也有效；重新 `attach()` 得到的 RunHandle 不共享。委托时需要申请 `QoniScopes.SITE_LOGIN_REQUEST` 和 `QoniScopes.SITE_LOGIN_CONFIRM`，并在 AccessKey 权限策略中允许这两个 scope。`openLogin()` 返回值上的 `confirm()` 仍然保留，供自己保存登录的调用方使用，已标记为弃用。
 
-上面用到的判别字符串也都导出成了常量，避免裸写字面量：`InteractionTypes`（`site_login` / `clarification` / `confirmation` / `take_control` / `wait`）、`InteractionStatuses`、`ActionKinds`（`i.can(...)` 的动作名）。授权 scope 同样有：`QoniScopes`（每个单独 scope）、`QoniProductScopes`（`products` 语法糖展开成的 per-product `read`+`manage` 对）、`QoniScopeBundles`（精选 bundle）。用它们代替手写字符串：
+上面用到的判别字符串也都导出成了常量，避免裸写字面量：`InteractionTypes`（`SiteLogin` / `TakeControl` / `AskUser` / `Confirmation` / `Wait`；已弃用的 `Clarification` 现在等于 `AskUser`）、`InteractionStatuses`、`ActionKinds`（`handle.can(...)` 的动作名）。授权 scope 同样有：`QoniScopes`（每个单独 scope）、`QoniProductScopes`（`products` 语法糖展开成的 per-product `read`+`manage` 对）、`QoniScopeBundles`（精选 bundle）。用它们代替手写字符串：
 
 ```ts
 import { InteractionTypes, ActionKinds, QoniScopes } from "@qoniai/qoni";
 
-if (i.type === InteractionTypes.Clarification && i.can(ActionKinds.answer)) {
-  await i.answer("蓝色那个按钮");
+if (handle.type === InteractionTypes.AskUser && handle.can(ActionKinds.answer)) {
+  await handle.answer("蓝色那个按钮");
 }
 ```
 
@@ -638,7 +667,7 @@ if (i.type === InteractionTypes.Clarification && i.can(ActionKinds.answer)) {
 
 原始 wire 事件类型（`run.action.started` 这种内部传输名，命名是历史遗留、也不一致）**不作为公开导出**——开发者按上面那套精选 `event.type` 匹配即可；极少数要精确 wire 的场景，`event.raw.event` 是个原始字符串，直接比对。
 
-Browser Use 的 scope 已预留，但产品运行时 SDK 方法导出前不作为公开方法说明。Site Login 的 scope（`QoniScopes.SITE_LOGIN_REQUEST`、`QoniScopes.SITE_LOGIN_CONFIRM`）用于运行交互上的 `InteractionHandle.openLogin()` 和 `confirm()`。
+Browser Use 的 scope 已预留，但产品运行时 SDK 方法导出前不作为公开方法说明。Site Login 的 scope（`QoniScopes.SITE_LOGIN_REQUEST`、`QoniScopes.SITE_LOGIN_CONFIRM`）用于运行交互上的 `InteractionHandle.openLogin()` 和 `confirmSignedIn()`。
 
 ### 返回结构