@qoniai/qoni 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## Unreleased — GenAuth communication
+
+- Add 111 Agent Mail/Phone runtime and administration methods with typed inputs/results.
+- Add native GenAuth credential exchange, bounded polling, idempotency and revision headers, and nested communication error codes.
+- Add bilingual SDK reference content and read-only live acceptance checks; current hosted Phone routes remain unavailable.
+
+
+## Unreleased
+
+- Add 591 GenAuth / Authing v3 management methods across 35 namespaces, aligned with all 496 JSON management methods in the official Authing Node SDK 4.0.2 plus GenAuth extensions and compatibility names. Include typed inputs/results, domain shortcuts and the flat `genauth.management` migration entry.
+- Preserve official SDK defaults and method names; support management PUT operations and safely interpolate DELETE path identifiers. Pin the upstream contract and include its MIT notice.
+- Add `genauth.users.iterate` for streaming paginated user lists and management request cancellation.
+- Coalesce concurrent management-token exchanges, honor JWT expiry and refresh once after automatic-token auth rejection.
+- Surface HTTP-200 GenAuth business errors even with `data`, preserving numeric Authing API codes and request IDs.
+- Preserve the existing user helpers; add generated contract/catalog maintenance, isolated live management acceptance and integration documentation.
+
+## Unreleased — next version: 0.10.0
+
+These public API changes require **0.10.0**, not a 0.9.x patch. This work does
+not bump the packaged version, publish, or release it.
+
+### Breaking
+
+- `track.create` requires an explicit schedule. Migrate to an integer
+  `{ kind: "interval", intervalSeconds: 600..2592000 }` or an explicit
+  `{ kind: "daily", at: "HH:MM", tz }`; daily starts up to 30 minutes early.
+  Cron is locally unsupported and is never automatically converted.
+- Interval `tz` and old targetUrls/extractionSchema/triggerDsl/
+  stopConditionDsl/notifyChannel/url fields have no wire equivalent. Remove
+  them; put watched URLs explicitly in prompt instructions. Optional undefined
+  fields are still omitted; defined unsupported fields raise typed local errors.
+- `refine` accepts title/schedule only. Create a new Track to change the original
+  prompt/intent; the raw updateMonitor wire API supports explicit instructions.
+- `runNow` returns only `{ trackId, sessionId, runId }`, a 202 acceptance
+  reference. TrackTaskRef is a type alias and remains assignable to JsonObject.
+  Read the exact recent check for its real `done/failed/expired/canceled`
+  status; this differs from RunResult's `succeeded`. Create already starts a
+  first look: wait for the original lastTaskId before one explicit runNow.
+- `runs` and `run(id)` search only the newest 50 checks; no extracted/diffs/
+  snapshot fields are synthesized. Replace old tick/snapshot consumers with
+  the actual check fields; a missing run raises local not_found with its range.
+- Track events/interactionHandle/api.events/api.intervene and DoAnything
+  readArtifacts now raise local QoniUnsupportedError with zero HTTP. Their
+  deprecated exports remain; use Track checks, separately authorized DoAnything
+  interactions, real file artifacts(), or captured screenshot events instead.
+- Pause/delete stop future scheduling and keep an in-flight check running.
+
+### Changed
+
+- Track now maps supported operations to `/track/tracks`: prompt → instructions,
+  explicit integer intervals of 600–2592000 seconds or daily at/tz (starts
+  0–30 minutes before target), real status PATCH, empty DELETE204, recent 50
+  checks with local pagination, and runNow task references. Refine is limited
+  to title/schedule. Deletion does not cancel a running task.
+- Cron, old extraction/DSL/URL/channel options, Track events/intervene and
+  interactionHandle fail locally. Deprecated methods/types remain exported.
+- `doAnything.api.readArtifacts` and snapshot types are deprecated with local
+  `QoniUnsupportedError` (`unsupported.operation`), zero HTTP. Use actual file
+  artifacts or captured screenshot events. File APIs are unchanged.
+- Live coverage metadata retires old monitor/snapshot success claims; current
+  Track mapping is locally verified, with live acceptance pending.
+
 ## 0.9.0 - 2026-10-07
 
 DoAnything interactions are now typed by what the user has to do, never by

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.
@@ -486,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
@@ -632,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
@@ -645,7 +718,7 @@ 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)
 
@@ -761,7 +834,7 @@ if (handle.type === InteractionTypes.AskUser && handle.can(ActionKinds.answer))
 
 ### 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).
 
@@ -794,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
@@ -814,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
@@ -846,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`. |
@@ -936,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.

package/README.zh-CN.md

@@ -118,6 +118,25 @@ await qoni.genauth.users.update({
 // await qoni.genauth.users.deleteBatch({ userIds: [profile.data.userId] });
 ```
 
+### GenAuth 管理功能
+
+`qoni.genauth` 现在提供 **35 个命名空间、591 个管理方法**，以 [Authing 官方 Node SDK 4.0.2](https://github.com/Authing/authing-node-sdk) 为参考，覆盖其全部 496 个 JSON 管理方法，并保留 GenAuth 扩展及兼容名称。除用户、角色、组织、应用和资源授权外，还包括岗位、公共账号、邀请、元数据、审批和风险名单。所有方法复用 Qoni AK/SK 管理 Token 交换，具备 TypeScript 参数及返回类型，并支持取消请求；实际部署的功能开关和权限仍决定接口可用性。
+
+```ts
+await qoni.genauth.groups.create({ code: "engineering", name: "工程团队" });
+await qoni.genauth.groups.addMembers({ code: "engineering", userIds: ["USER_ID"] });
+
+// 沿用 Authing v3 方法名称的调用入口：
+const roles = await qoni.genauth.management.listRoles({ namespace: "project", page: 1, limit: 20 });
+
+// 自动逐页读取；break 后不会请求下一页：
+for await (const user of qoni.genauth.users.iterate({ limit: 50 })) {
+  console.log(user.userId);
+}
+```
+
+[使用指南](./docs/genauth-management.md) · [完整 API 清单](./docs/genauth-management-api.md)。角色需属于已存在的权限分组；删除用户仍需遵循 GenAuth 的在职与离职规则。
+
 ### 运行时产品委托
 
 GUMem、WebAgent、Do Anything、Web Search、Track 是代表终端用户执行的运行时产品能力。silent 委托需要一个来自 Qoni credential 绑定 userpool 的真实 GenAuth 用户 ID，再使用 `delegateToken` 返回的 token。
@@ -453,43 +472,93 @@ const followUp = await qoni.deepResearch.run({
 });
 ```
 
+`doAnything.api.readArtifacts()` 及导出类型 `DoAnythingSnapshot`、`SnapshotImage`、
+`SnapshotAction` 已 deprecated：该结构化快照契约从未有后端路径或字段来源。
+方法本地抛 `QoniUnsupportedError(code: "unsupported.operation")`，零 HTTP。
+文件请用 `qoni.doAnything.artifacts({ token, runId })` / `api.listArtifacts()`，下载用 `artifact.content()` /
+`api.artifactDownloadUrl()`；图片请开启 `capture: { screenshots: true }` 并读取
+screenshot events。文本文件不是 snapshot，真实文件 artifacts API 保持。
+
 ### Track
 
+Track 使用真实 `/track/tracks`。`prompt` 原样映射到 `instructions`，目标 URL
+请明确写在描述中。必须显式指定 schedule：整数 600–2592000 秒 interval，或带
+时区的 daily。daily 在目标时间前 0–30 分钟启动，不保证整点启动。
+
 ```ts
+import type { MonitorSchedule } from "@qoniai/qoni";
+
 const monitor = await qoni.track.create({
   token,
-  prompt: "每分钟监控一次比特币价格。",
-});
+  prompt: "监控 https://example.com/policy 并报告变化。",
+  title: "政策变化",
+  schedule: { kind: "interval", intervalSeconds: 3600 },
+}); // create 立即启动 first_look 首次检查
+const initial = await monitor.get();
+const firstRunId = initial.lastTaskId; // 只捕获一次原始首检 ID
+if (typeof firstRunId !== "string" || !firstRunId) throw new Error("缺少初始 lastTaskId");
+const sameMonitor = await qoni.track.attach(monitor.id, { token });
 
-// 新建的 monitor 先处于 `pending_clarification`（后端把意图对齐成具体规格），
-// 几秒后转为 `active`（意图含糊时可能先发一个 interaction）。runNow()/refine()
-// 都要求 `active`，所以先等它就绪再操作：
-for await (const event of monitor.events()) {
-  if (event.type === "interaction") {
-    const i = monitor.interactionHandle(event.data); // 如意图澄清
-    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); // 在最近 50 条中按原始 ID 精确查找
+    if (["done", "failed", "expired", "canceled"].includes(String(check.status))) {
+      if (check.status !== "done") throw new Error(`检查 ${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(`检查 ${runId} 超时`);
 }
 
-await monitor.runNow();                     // 立即触发一次 tick
-const ticks = await monitor.runs({ limit: 10 }); // tick 产生的 run 只读列表
+try {
+  await monitor.pause(); // 停止未来调度，已经启动的首检继续
+  await waitForCheck(firstRunId);
+  await monitor.refine({ schedule: initial.schedule as MonitorSchedule }); // 本次已校验的已知输入可 roundtrip
+  await monitor.refine({ schedule: { kind: "daily", at: "09:00", tz: "Asia/Singapore" } });
+  const task = await monitor.runNow(); // 调度暂停时，显式手动执行一次
+  const check = await waitForCheck(task.runId); // 202 接受不等于完成
+  const checks = await monitor.runs({ limit: 10, offset: 0 });
+  await monitor.resume();
+} finally {
+  await monitor.delete(); // 软删除；仍在运行的检查继续
+}
+```
 
-// 用 refine() 改定义（任意字段子集：schedule / targetUrls / extractionSchema /
-// triggerDsl / stopConditionDsl / notifyChannel）。`schedule` 是
-// { 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 但不删除
-await monitor.resume();
-await monitor.delete();
+create 会立即启动一次 `first_look` 首检。只捕获一次初始 `lastTaskId`，等待
+同一个首检结束，再显式调用一次 runNow。并发启动其他任务仍可能导致 409，SDK
+原样抛出，不隐式重试。pause 只暂停未来调度，已经启动的检查继续。
 
-// 之后可以用存下来的 id 重连：
-const sameMonitor = await qoni.track.attach(monitor.id, { token });
-```
+Track check.status 为 `running/done/failed/expired/canceled`，成功终态是 **done**，
+原样保留，区别于单次 RunResult.status 的 succeeded。读回已知 wire schedule 形状
+时不重新套用 SDK 写入边界或 Intl 时区校验；未知/不完整形状原样保留。写入仍严格
+校验，请选择支持的输入，不要把任意服务端 schedule 强制 cast 后重写。
+
+`runs()` 查询后端最近 50 条 checks，再在本地应用 limit/offset；`run(id)` 只在
+同一窗口按精确 run_id 查找，未找到抛本地 `QoniError(code: "not_found")`（没有 HTTP status）并说明范围；Track 本身不存在是后端 404 `track_not_found`。
+检查保留真实 status/outcome/headline/answer/failure，不补造 extracted、diffs 或
+snapshotId。早前任务仍在运行时，`runNow()` 会原样抛后端 409 `task_in_progress`；
+成功只返回真实任务引用，完成与否需要再读 checks。
+
+| 保留的方法或输入 | 当前行为 |
+| --- | --- |
+| `track.create`、`attach`、`MonitorHandle.get` | 创建/读取真实 Track；get 转换已知 schedule 形状，未知形状原样保留。 |
+| `MonitorHandle.pause`、`resume` | PATCH status 为 paused / active；pause 不停已启动的检查。 |
+| `MonitorHandle.refine` | 仅修改 title/schedule；改 prompt/instructions/intent 需新建 Track。 |
+| `MonitorHandle.runNow` | POST run_now，返回真实任务引用。 |
+| `MonitorHandle.runs`、`run` | 仅以 Track read scope 读取最近检查，不回退到 DoAnything。 |
+| `MonitorHandle.delete` | DELETE204 软删除停止调度，不取消正在运行的任务。 |
+| `track.api.createMonitor`、`getMonitor` | 保留旧方法名；真实字段为 instructions/title，wire schedule 为 `{ every_seconds: N }` 或 `{ daily_at: "HH:MM", tz }`。 |
+| `track.api.updateMonitor` | PATCH 真实 title/instructions/schedule/status；低层可改 instructions，高层 refine 不允许。 |
+| `track.api.runNow`、`deleteMonitor` | 真实 run_now / DELETE；wire 任务引用 / 空 204。 |
+| `track.api.listRuns`、`getRun` | 原始 checks，本地分页，精确查找最近 50 条。 |
+| `MonitorHandle.events`、`interactionHandle`、`track.api.events`、`intervene` | deprecated，无后端路径，本地 QoniUnsupportedError，零 HTTP/零 token exchange。 |
+| `targetUrls`、`extractionSchema`、`triggerDsl`、`stopConditionDsl`、`notifyChannel`（含 snake_case 别名）、旧 `url` | 无对应字段，本地 QoniUnsupportedError；URL 需明确写入 prompt。 |
+| cron schedule | deprecated，本地明确拒绝并给出 daily 替代，不默默转换任意 cron。 |
+
+无 schedule、非法 interval/时间/时区/分页等输入在 HTTP 前抛 `QoniValidationError`。
+旧类型导出与 cron 分支保留并标记 deprecated；值为 undefined 的可选键保持省略行为，有值的不支持字段仍拒绝；unsupported 负例不算能力正例。
 
 ### GenAuth 用户上下文与用户管理
 
@@ -582,7 +651,7 @@ interface RunResult {
   runId: string;
   status: "succeeded" | "failed" | "canceled";  // run 的交付状态
   output?: unknown;            // 最终答案 / 载荷（形状随任务而定）
-  artifacts: Artifact[];       // 交付物——deepResearch 报告；其它产品为 []
+  artifacts: Artifact[];       // 持久化 DoAnything 文件 / deepResearch 报告
   isTaskSuccessful?: boolean;  // 任务是否达成目标（与 status 不同）
   terminalReason?: string;
   raw: JsonObject;             // 完整 wire envelope——成本、步数、token 用量
@@ -591,7 +660,7 @@ interface RunResult {
 
 每个 `Artifact` 暴露 `id`、`name?`、`mime?`、`sizeBytes?`、`createdAt?` 和 `content(): Promise<Uint8Array>`（懒加载字节）。其余方法都返回下文的 `QoniResponse<T>` 信封,`T` 是该调用的具体载荷类型（例如 `genauth.users.list` → `.data` 上的分页用户列表）。`T` 的精确形状见随包的 `.d.ts`，与后端契约一致。
 
-`MonitorHandle`（Track）提供 `id`、`get()`、`pause()`、`resume()`、`refine(patch)`、`runNow()`、`events()`、`interactionHandle()`、`runs()`、`run(runId)`、`delete()`。`runNow()` 和 `refine()` 要求 monitor 处于 `active`——新建的 monitor 会先短暂处于 `pending_clarification`（见上方 Track 示例）。
+`MonitorHandle`（Track）提供 `id`、`get()`、`pause()`、`resume()`、`refine(patch)`、`runNow()`、`runs()`、`run(runId)`、`delete()`。deprecated 的 `events()` / `interactionHandle()` 本地拒绝，完整逐项映射见上方 Track。
 
 ### 交互（HITL）
 
@@ -663,7 +732,7 @@ if (handle.type === InteractionTypes.AskUser && handle.can(ActionKinds.answer))
 
 ### Wire 级逃生舱
 
-与后端 HTTP 契约一一对应的低层方法保留在 `qoni.<product>.api.*` 下（如 `qoni.doAnything.api.createSession`、`qoni.deepResearch.api.followUp`、`qoni.track.api.createMonitor`）。这些方法直接镜像 wire 形状——snake_case 字段、双层 envelope 事件、run 操作统一走 `/{product}/runs/{run_id}` 单 ID 寻址——形状会随 API 演进变化，不在冻结的公开契约范围内。
+可支持的低层方法保留在 `qoni.<product>.api.*` 下（如 `qoni.doAnything.api.createSession`、`qoni.deepResearch.api.followUp`、`qoni.track.api.createMonitor`）。这些方法直接镜像 wire 形状——snake_case 字段、双层 envelope 事件、run 操作统一走 `/{product}/runs/{run_id}` 单 ID 寻址——形状会随 API 演进变化，不在冻结的公开契约范围内。
 
 原始 wire 事件类型（`run.action.started` 这种内部传输名，命名是历史遗留、也不一致）**不作为公开导出**——开发者按上面那套精选 `event.type` 匹配即可；极少数要精确 wire 的场景，`event.raw.event` 是个原始字符串，直接比对。
 
@@ -694,9 +763,9 @@ type QoniResponse<T> = {
 //     "phase"          string   —— Deep Research 阶段名
 //     "sectionReady"   string   —— Deep Research 章节标题
 //     "resultsReady"   number   —— Web Search 结果数
-//     "monitorCreated" string   —— Track monitor id
-//     "triggered"      string   —— Track 变化摘要
-//     "checkCompleted" boolean  —— Track:这次检查有没有发现变化
+//     "monitorCreated" string   —— deprecated 的旧 monitor wire 类型
+//     "triggered"      string   —— deprecated 的旧 monitor wire 类型
+//     "checkCompleted" boolean  —— deprecated 的旧 monitor wire 类型
 //   丰富事件 —— event.data 是个小对象:
 //     "message"        { text, role }
 //     "interaction"    带类型的 Interaction 对象（HITL）—— 见「交互」一节
@@ -713,7 +782,7 @@ type QoniResponse<T> = {
 | Do Anything | 核心:`progress` / `message` / `interaction` / `screenshot` / `browserLiveUrlChanged` / `done` |
 | Web Search | 核心 + `resultsReady` |
 | Deep Research | 核心 + `phase` / `sectionReady`（大纲审批走 `interaction`） |
-| Track（`MonitorHandle`） | 核心 + `monitorCreated` / `triggered` / `checkCompleted` |
+| Track（`MonitorHandle`） | 无 SSE 路径，旧 MonitorEvent 类型 deprecated；用 runs()/run() 读取检查。 |
 
 展示实时浏览器时，监听 `browserLiveUrlChanged`，用 `event.data.liveUrl` 更新预览地址。任务执行期间可能切换标签页，因此不能只使用第一次收到的地址。`forceViewerReload` 为 true 时重载已有预览。live URL 可访问浏览器画面，不要写入公开日志。
 
@@ -739,6 +808,7 @@ type QoniEvent<T = unknown> = {
 
 | 类 | 触发时机 | 典型处理 |
 | --- | --- | --- |
+| `QoniUnsupportedError` | 保留表面没有后端操作（code: `unsupported.operation`），零 HTTP。 | 使用错误提示中的真实替代能力。 |
 | `QoniValidationError` | 请求发出前的本地校验失败（scope 字符串格式错、silent 委托缺 user）。 | 按消息修正调用——消息里给出正确写法。 |
 | `QoniAuthError` | AK/SK 签名被 Qoni 拒绝（凭据错误/已轮换）。 | 检查 `accessKey` / `secretKey`。 |
 | `QoniPermissionDeniedError` | AccessKey 或 delegation token 缺少所需 scope（403）。 | 检查 AccessKey 权限策略，并在 `delegateToken` 中申请所需 scope。 |
@@ -827,3 +897,20 @@ const artifacts = await client.doAnything.artifacts({ token, runId: run.id });
 ```
 
 Wire methods: `client.doAnything.api.listArtifacts(...)` and `artifactDownloadUrl(...)`.
+
+## Agent Mail 与 Agent Phone
+
+本地通信扩展提供 `qoni.genauth.agentMail` 和 `qoni.genauth.agentPhone` 的运行侧与管理侧 API。运行侧通过 `genauthCommunicationCredentials` 配置原生 GenAuth 凭据；管理侧复用 Qoni 的兑换流程。详见 [通信指南](docs/genauth-communication.md) 与 [方法索引](docs/genauth-communication-api.md)。
+
+## 本地 Agent 整合扩展
+
+整合分支增加 `qoni.genauth.auth.createLoginUrl` / `exchangeLoginCode` 与
+`qoni.genauth.agents.create` / `get` / `bind` / `bindUser`，并保留原有管理、
+Agent Mail 和 Agent Phone 接口。这些新增内容尚未发布到 npm。登录回调必须先核对
+App 保存的 `state`，再兑换一次性 code。Personal 邮箱委托必须指定真实 IAM
+`agentId`，审计标签不能证明邮箱归属。创建可能仍处于 pending；结果未知时只能使用
+原 provisioning 引用或幂等键核对，不能重新创建资源。
+
+Personal Quickstart 的邮箱创建流程与统一 Agent 管理的可选能力模型分别保留。
+统一管理中身份、邮箱、手机号均可选，一个 Agent 可以拥有多个邮箱和手机号。
+绑定 Personal 身份不会签发凭据，也不会自动打通 IAM token 调用原生 Mail/Phone API。