@qoniai/qoni 0.8.0 → 0.9.1

package/README.md

@@ -5,7 +5,7 @@
 [![Package manager](https://img.shields.io/badge/package%20manager-pnpm-f69220)](https://pnpm.io/)
 [![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-Unified Node.js SDK for Qoni Agent delegation, GenAuth user management, GUMem memory, WebAgent automation, web search, and monitoring.
+Unified Node.js SDK for Qoni Agent delegation, GenAuth management, GUMem memory, WebAgent automation, web search, and monitoring.
 
 `@qoniai/qoni` gives a trusted server one compact way to use Qoni AK/SK. For runtime product calls, your service verifies the GenAuth user, requests short-lived delegation with `delegateToken`, and then uses the returned token in GUMem, WebAgent, Do Anything, Web Search, and Track calls. For GenAuth user management, the SDK exchanges AK/SK for a standard GenAuth management token internally and calls GenAuth v3 users APIs with that token.
 
@@ -125,6 +125,21 @@ await qoni.genauth.users.update({
 // await qoni.genauth.users.deleteBatch({ userIds: [profile.data.userId] });
 ```
 
+### GenAuth Management
+
+`qoni.genauth` exposes **591 typed management methods across 35 namespaces**, aligned with [Authing's official Node SDK 4.0.2](https://github.com/Authing/authing-node-sdk). This includes all 496 official JSON management methods plus GenAuth extensions and compatibility names, including positions, public accounts, invitations, metadata, approvals and risk lists. Calls share the Qoni AK/SK management-token exchange and support cancellation. Deployment features and permissions still determine endpoint availability.
+
+```ts
+await qoni.genauth.groups.create({ code: "engineering", name: "Engineering" });
+await qoni.genauth.groups.addMembers({ code: "engineering", userIds: ["USER_ID"] });
+const roles = await qoni.genauth.management.listRoles({ namespace: "project", page: 1, limit: 20 });
+for await (const user of qoni.genauth.users.iterate({ limit: 50 })) {
+  console.log(user.userId);
+}
+```
+
+[Integration guide](./docs/genauth-management.md) · [Complete API catalog](./docs/genauth-management-api.md). Roles belong to an existing permission namespace. GenAuth employment and departure rules still apply when deleting users.
+
 ### Runtime Product Delegation
 
 GUMem, WebAgent, Do Anything, Web Search, and Track act for an end user. Silent delegation calls need a real GenAuth user id from the userpool bound to the Qoni credential, then a `delegateToken` result.
@@ -151,7 +166,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 +301,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 +332,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 +353,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 +372,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 +386,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.
 
@@ -471,46 +501,104 @@ const followUp = await qoni.deepResearch.run({
 });
 ```
 
+`doAnything.api.readArtifacts()` and the exported `DoAnythingSnapshot`,
+`SnapshotImage`, and `SnapshotAction` types are deprecated. There has never been
+a backend endpoint/source for that structured snapshot contract. The method
+raises local `QoniUnsupportedError` (`code: "unsupported.operation"`) with zero
+HTTP. Use `qoni.doAnything.artifacts({ token, runId })` / `api.listArtifacts()` for files, including
+`artifact.content()` or `api.artifactDownloadUrl()` for downloads. Use
+`capture: { screenshots: true }` and screenshot events for images. A text file
+artifact is not a snapshot; the real file APIs are unchanged.
+
 ### Track
 
+Track uses `/track/tracks`. `prompt` maps to `instructions`; include watched URLs
+in that text. An explicit schedule is required: an integer interval of
+600–2592000 seconds, or a daily time with a time zone. A daily check starts
+0–30 minutes before the target time, rather than exactly at that time.
+
 ```ts
+import type { MonitorSchedule } from "@qoniai/qoni";
+
 const monitor = await qoni.track.create({
   token,
-  prompt: "Monitor the price of Bitcoin every minute.",
-});
+  prompt: "Watch https://example.com/policy and report changes.",
+  title: "Policy changes",
+  schedule: { kind: "interval", intervalSeconds: 3600 },
+}); // create immediately starts a first_look check
+const initial = await monitor.get();
+const firstRunId = initial.lastTaskId; // capture this original ID once
+if (typeof firstRunId !== "string" || !firstRunId) throw new Error("Missing initial lastTaskId");
+const sameMonitor = await qoni.track.attach(monitor.id, { token });
 
-// A new monitor starts in `pending_clarification` while the backend aligns
-// the intent into a concrete spec, then flips to `active` (usually a few
-// seconds; it may emit an `interaction` first if the intent is ambiguous).
-// 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. an intent clarification
-    if (i.can("confirm")) await i.confirm();
-    continue;
-  }
-  const { status } = await monitor.get();
-  if (status === "active") break;
+async function waitForCheck(runId: string) {
+  const deadline = Date.now() + 300_000;
+  do {
+    const check = await monitor.run(runId); // exact ID in the recent 50 checks
+    if (["done", "failed", "expired", "canceled"].includes(String(check.status))) {
+      if (check.status !== "done") throw new Error(`Check ${runId} ${String(check.status)}: ${String(check.failure ?? "")}`);
+      return check;
+    }
+    await new Promise(resolve => setTimeout(resolve, Math.min(1000, Math.max(0, deadline - Date.now()))));
+  } while (Date.now() < deadline);
+  throw new Error(`Check ${runId} timed out`);
 }
 
-await monitor.runNow();                     // trigger an immediate tick
-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 } (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
-await monitor.resume();
-await monitor.delete();
-
-// Reconnect later from a stored id:
-const sameMonitor = await qoni.track.attach(monitor.id, { token });
+try {
+  await monitor.pause(); // pause future scheduling; the first look continues
+  await waitForCheck(firstRunId);
+  await monitor.refine({ schedule: initial.schedule as MonitorSchedule }); // our known, validated input roundtrips
+  await monitor.refine({ schedule: { kind: "daily", at: "09:00", tz: "Asia/Singapore" } });
+  const task = await monitor.runNow(); // one explicit manual check while scheduling is paused
+  const check = await waitForCheck(task.runId); // 202 acceptance is not completion
+  const checks = await monitor.runs({ limit: 10, offset: 0 });
+  await monitor.resume();
+} finally {
+  await monitor.delete(); // soft-delete; any in-flight check continues
+}
 ```
 
+Create immediately starts a `first_look` check. Capture its initial `lastTaskId`
+and wait for that same check before one explicit `runNow()`. A concurrent run
+can still cause 409; the SDK surfaces it and never retries. Pause stops future
+scheduled checks and keeps any started check running.
+
+Track check `status` is `running`, `done`, `failed`, `expired`, or `canceled`;
+`done` is the successful terminal value. It is kept verbatim and differs from
+one-shot `RunResult.status: "succeeded"`. Known wire schedule shapes are read
+without revalidating server values against SDK write bounds or Intl time zones;
+unknown/incomplete shapes remain verbatim. Writing a schedule stays strict, so
+validate/choose supported input rather than casting every server value back.
+
+`runs()` retrieves the backend's newest 50 checks and applies `limit`/`offset`
+locally. `run(id)` searches that same bounded window; a missing ID raises
+`QoniError` with local `code: "not_found"` (no HTTP status) and explains the range. A missing Track itself is the backend 404 `track_not_found`. Checks expose the
+actual status, outcome, headline, answer and failure; no extraction, diffs or
+snapshot IDs are synthesized. `runNow()` can return the backend's 409
+`task_in_progress` while an earlier task is working. It returns a task reference
+on 202; read checks to observe completion.
+
+| Retained surface | Current behavior |
+| --- | --- |
+| `track.create`, `track.attach`, `MonitorHandle.get` | Create/read the real Track resource; get converts known wire schedules; unknown shapes stay verbatim. |
+| `MonitorHandle.pause`, `resume` | PATCH `status: paused` / `active`; pause keeps an in-flight check running. |
+| `MonitorHandle.refine` | PATCH title/schedule only; changing prompt/instructions/intent requires a new track. |
+| `MonitorHandle.runNow` | POST `run_now`; returns the actual task reference. |
+| `MonitorHandle.runs`, `run` | Read recent checks with Track read scope only; no DoAnything fallback. |
+| `MonitorHandle.delete` | DELETE 204; soft deletion stops scheduling and does not cancel running work. |
+| `track.api.createMonitor`, `getMonitor` | Historical names retained; use real `instructions`, `title`, and wire schedule `{ every_seconds: N }` or `{ daily_at: "HH:MM", tz }`. |
+| `track.api.updateMonitor` | PATCH real title/instructions/schedule/status fields; wire API permits instructions, while high-level refine does not. |
+| `track.api.runNow`, `deleteMonitor` | Real `run_now` / DELETE; raw task reference / empty 204. |
+| `track.api.listRuns`, `getRun` | Raw checks, local limit/offset, exact lookup within recent 50. |
+| `MonitorHandle.events`, `interactionHandle`, `track.api.events`, `intervene` | Deprecated; no backend endpoint. Local `QoniUnsupportedError`, zero HTTP or token exchange. |
+| `targetUrls`, `extractionSchema`, `triggerDsl`, `stopConditionDsl`, `notifyChannel` (including snake_case aliases), legacy `url` | No backend equivalent; rejected locally with `QoniUnsupportedError`. Put URLs in the prompt explicitly. |
+| Cron schedule | Deprecated and rejected locally with a daily alternative. Arbitrary cron is never silently converted. |
+
+A missing schedule, malformed input, invalid interval/time/zone, or invalid
+pagination raises `QoniValidationError` before HTTP. `MonitorSchedule` retains
+the deprecated cron branch; optional undefined fields retain omission behavior, while specified unsupported fields fail; historical event and option types remain exported
+for source compatibility. Unsupported methods are not successful capability tests.
+
 ### GenAuth User Context and Management
 
 ```ts
@@ -617,7 +705,7 @@ interface RunResult {
   runId: string;
   status: "succeeded" | "failed" | "canceled";  // delivery status of the run
   output?: unknown;            // final answer / payload (shape is task-specific)
-  artifacts: Artifact[];       // deliverables — deepResearch reports; [] for the others
+  artifacts: Artifact[];       // persisted DoAnything files / deepResearch reports
   isTaskSuccessful?: boolean;  // did the task achieve its goal (distinct from `status`)
   terminalReason?: string;
   raw: JsonObject;             // full wire envelope — cost, step counts, token usage
@@ -630,95 +718,127 @@ is the typed payload for that call (e.g. `genauth.users.list` → a paged user
 list on `.data`). The exact `T` shapes live in the bundled `.d.ts` and follow
 the backend contract.
 
-`MonitorHandle` (Track) exposes `id`, `get()`, `pause()`, `resume()`, `refine(patch)`, `runNow()`, `events()`, `interactionHandle()`, `runs()`, `run(runId)`, and `delete()`. `runNow()` and `refine()` require the monitor to be `active` — a freshly created monitor is briefly `pending_clarification` first (see the Track example).
+`MonitorHandle` (Track) provides `id`, `get()`, `pause()`, `resume()`, `refine(patch)`, `runNow()`, `runs()`, `run(runId)`, and `delete()`. Its deprecated `events()` and `interactionHandle()` methods fail locally; see Track above for the complete mapping.
 
 ### 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:
-
-```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();
-  }
-}
-```
+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:
 
-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;
+  }
 }
+
+const result = await run.wait({ onInteraction: handleInteraction });
 ```
 
-`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
+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");
 }
 ```
 
 ### Wire-Level Escape Hatch
 
-The 1:1 low-level methods live under `qoni.<product>.api.*` (e.g. `qoni.doAnything.api.createSession`, `qoni.deepResearch.api.followUp`, `qoni.track.api.createMonitor`). These mirror the backend HTTP contract directly — snake_case fields, double-envelope events, single-ID `/{product}/runs/{run_id}` addressing for run operations — and their shapes may evolve with the API. They are not part of the frozen public contract.
+Supported low-level methods live under `qoni.<product>.api.*` (e.g. `qoni.doAnything.api.createSession`, `qoni.deepResearch.api.followUp`, `qoni.track.api.createMonitor`). These mirror the backend HTTP contract directly — snake_case fields, double-envelope events, single-ID `/{product}/runs/{run_id}` addressing for run operations — and their shapes may evolve with the API. They are not part of the frozen public contract.
 
 `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
 
@@ -747,9 +867,9 @@ that type:
 //     "phase"          string   — the Deep Research phase name
 //     "sectionReady"   string   — the Deep Research section title
 //     "resultsReady"   number   — Web Search count of unique results
-//     "monitorCreated" string   — Track monitor id
-//     "triggered"      string   — Track change summary
-//     "checkCompleted" boolean  — Track: did the scheduled check find a change
+//     "monitorCreated" string   — deprecated legacy monitor wire type
+//     "triggered"      string   — deprecated legacy monitor wire type
+//     "checkCompleted" boolean  — deprecated legacy monitor wire type
 //   RICH events — event.data is a small object:
 //     "message"        { text, role }
 //     "interaction"    the typed Interaction object (HITL) — see Interactions
@@ -767,7 +887,7 @@ Each product handle is typed to its own subset:
 | 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` |
+| Track (`MonitorHandle`) | No SSE endpoint; historical MonitorEvent types are deprecated. Read checks with runs()/run(). |
 
 For a live browser preview, listen for `browserLiveUrlChanged` and show
 `event.data.liveUrl` in your viewer. A run can switch browser tabs after its
@@ -799,6 +919,7 @@ All error classes are exported and can be matched with `instanceof`:
 
 | Class | Fires when | Typical recovery |
 | --- | --- | --- |
+| `QoniUnsupportedError` | Retained surface has no backend operation (code: `unsupported.operation`); zero HTTP. | Use the alternative named in the error. |
 | `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 AccessKey or delegation token lacks a required scope (403). | Check the AccessKey permission policy and request the missing scope with `delegateToken`. |
@@ -889,3 +1010,23 @@ const artifacts = await client.doAnything.artifacts({ token, runId: run.id });
 ```
 
 Wire methods: `client.doAnything.api.listArtifacts(...)` and `artifactDownloadUrl(...)`.
+
+## Agent Mail and Agent Phone
+
+The local GenAuth communication extension provides `qoni.genauth.agentMail` and `qoni.genauth.agentPhone`, including runtime and administrator APIs. Runtime requires native GenAuth credentials via `genauthCommunicationCredentials`; administration reuses Qoni token exchange. See [the communication guide](docs/genauth-communication.md) and [method index](docs/genauth-communication-api.md).
+
+## Local Agent integration extension
+
+The integration branch adds `qoni.genauth.auth.createLoginUrl` / `exchangeLoginCode` and
+`qoni.genauth.agents.create` / `get` / `bind` / `bindUser`, alongside the existing
+management, Agent Mail and Agent Phone APIs. These additions are not an npm release.
+The hosted-login callback must validate the App's stored `state` before exchanging
+the one-use code. Personal mailbox delegation requires a formal IAM `agentId`; an
+audit label does not prove mailbox ownership. A Personal creation response may still
+be pending; an unknown result must be reconciled using its original provisioning
+reference or idempotency key, without starting another creation.
+
+The Personal Quickstart email creation flow is separate from the unified Agent
+management model, where identity, email and phone are optional capabilities and an
+Agent may have multiple email addresses and phone numbers. Personal binding does
+not issue credentials or enable IAM-token access to the native Mail/Phone APIs.