@qoniai/qoni 0.8.0 → 0.9.1

package/docs/genauth-management.md

@@ -0,0 +1,285 @@
+---
+title: GenAuth 管理 SDK
+description: 初始化 SDK，管理用户、用户组、组织、角色、权限、应用和自定义字段。
+status: draft
+sdkCandidate: contracts/genauth-management.json
+lastReviewed: 2026-10-12
+pageClass: qoni-sdk-management
+---
+
+## 初始化
+
+```ts
+import { Qoni } from '@qoniai/qoni'
+
+const qoni = new Qoni({
+  accessKey: process.env.QONI_ACCESS_KEY!,
+  secretKey: process.env.QONI_SECRET_KEY!,
+})
+```
+
+使用绑定目标 GenAuth 用户池的 Qoni 访问密钥，在服务端调用。
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `accessKey` | `string` | 是 | Qoni 访问密钥 |
+| `secretKey` | `string` | 是 | Qoni 访问密钥 Secret |
+| `host` | `string` | 否 | 私有部署的 Qoni 服务地址 |
+| `genauthHost` | `string` | 否 | 指定 GenAuth 服务地址 |
+| `timeoutMs` | `number` | 否 | 请求超时，单位毫秒，默认 `30000` |
+| `fetch` | `typeof fetch` | 否 | 自定义 HTTP transport |
+
+## 用户管理
+
+```ts
+const { data: user } = await qoni.genauth.users.create({
+  username: 'sdk-example-user',
+  name: 'Example user',
+})
+
+const { data: userDetails } = await qoni.genauth.users.get({ userId: user.userId })
+await qoni.genauth.users.update({ userId: user.userId, nickname: 'Alice' })
+const { data: userBatch } = await qoni.genauth.users.getBatch({ userIds: [user.userId] })
+```
+
+| 方法 | 功能 | 主要参数 | `data` |
+| --- | --- | --- | --- |
+| `users.create` | 创建用户 | username / email / phone；name、password 等可选 | 用户对象 |
+| `users.get` | 读取用户 | userId | 用户对象 |
+| `users.getBatch` | 批量读取用户 | userIds: string[] | 用户数组 |
+| `users.update` | 更新用户 | userId 与需要更新的字段 | 更新后的用户 |
+| `users.createBatch` | 批量创建用户 | list: 用户参数数组 | 用户数组 |
+| `users.deleteBatch` | 批量删除用户 | userIds: string[] | 删除结果 |
+
+创建时至少设置用户名、邮箱或手机号。删除在职用户前，先按业务流程通过 `users.resign({ userId })` 设置离职状态。
+
+## 用户查询与分页
+
+```ts
+const { data: userPage } = await qoni.genauth.users.list({
+  page: 1,
+  limit: 20,
+  keywords: 'alice',
+  options: { fuzzySearchOn: ['username', 'email'] },
+})
+console.log(userPage.list, userPage.totalCount)
+
+for await (const item of qoni.genauth.users.iterate({ limit: 50 })) {
+  console.log(item.userId)
+}
+```
+
+| 方法 | 功能 | 主要参数 | `data` |
+| --- | --- | --- | --- |
+| `users.list` | 分页查询用户 | page、limit、keywords、options | { list, totalCount } |
+| `users.iterate` | 逐个遍历用户 | page 默认 1，limit 默认 50、范围 1–50 | `AsyncIterable<User>` |
+
+`page` 从 1 开始。`keywords` 用于关键字筛选，`options.fuzzySearchOn` 指定匹配字段。无需筛选时省略这两个参数。`iterate` 中使用 `break` 停止遍历。
+
+## 用户组
+
+```ts
+const { data: group } = await qoni.genauth.groups.create({
+  code: 'engineering',
+  name: 'Engineering',
+})
+await qoni.genauth.groups.addMembers({ code: group.code, userIds: [user.userId] })
+const { data: groupPage } = await qoni.genauth.groups.list({ page: 1, limit: 20 })
+```
+
+| 方法 | 功能 | 主要参数 | `data` |
+| --- | --- | --- | --- |
+| `groups.create` | 创建用户组 | code、name | 用户组对象 |
+| `groups.get` | 读取用户组 | code | 用户组对象 |
+| `groups.list` | 查询用户组 | page、limit | { list, totalCount } |
+| `groups.update` | 更新用户组 | code 与更新字段 | 用户组对象 |
+| `groups.addMembers` | 添加成员 | code、userIds | 操作结果 |
+
+## 组织与部门
+
+```ts
+await qoni.genauth.organizations.create({
+  organizationCode: 'company',
+  organizationName: 'Example company',
+})
+const { data: department } = await qoni.genauth.departments.create({
+  organizationCode: 'company',
+  parentDepartmentId: 'root',
+  name: 'Engineering',
+  code: 'engineering',
+})
+await qoni.genauth.departments.addMembers({
+  organizationCode: 'company',
+  departmentId: department.departmentId,
+  userIds: [user.userId],
+})
+```
+
+| 方法 | 功能 | 主要参数 | `data` |
+| --- | --- | --- | --- |
+| `organizations.create` | 创建组织 | organizationCode、organizationName | 组织对象 |
+| `organizations.get` | 读取组织 | organizationCode | 组织对象 |
+| `organizations.list` | 查询组织 | page、limit | 组织列表 |
+| `organizations.update` | 更新组织 | organizationCode 与更新字段 | 组织对象 |
+| `departments.create` | 创建部门 | organizationCode、parentDepartmentId、name | 部门对象 |
+| `departments.get` | 读取部门 | organizationCode、departmentId 或 departmentCode | 部门对象 |
+| `departments.update` | 更新部门 | organizationCode、departmentId 与更新字段 | 部门对象 |
+| `departments.addMembers` | 添加部门成员 | organizationCode、departmentId、userIds | 操作结果 |
+
+根部门的 `parentDepartmentId` 使用 `root`；其他部门使用实际父部门 ID。
+
+## 角色、资源与授权
+
+```ts
+await qoni.genauth.namespaces.create({ code: 'project', name: 'Project' })
+await qoni.genauth.roles.create({ namespace: 'project', code: 'reader', name: 'Reader' })
+await qoni.genauth.roles.assign({
+  namespace: 'project',
+  code: 'reader',
+  targets: [{ targetType: 'USER', targetIdentifier: user.userId }],
+})
+await qoni.genauth.resources.create({
+  namespace: 'project', code: 'documents', type: 'API',
+  apiIdentifier: '/documents',
+  actions: [{ name: 'documents:read', description: 'Read documents' }],
+})
+await qoni.genauth.permissions.authorize({
+  namespace: 'project',
+  list: [{
+    targetType: 'ROLE', targetIdentifiers: ['reader'],
+    resources: [{ code: 'documents:*', resourceType: 'API', actions: ['documents:read'] }],
+  }],
+})
+const { data: permission } = await qoni.genauth.permissions.isAllowed({
+  namespace: 'project', userId: user.userId,
+  resource: 'documents:123', action: 'documents:read',
+})
+console.log(permission.allowed)
+```
+
+| 方法 | 功能 | 主要参数 | `data` |
+| --- | --- | --- | --- |
+| `namespaces.create` | 创建权限空间 | code、name | 权限空间对象 |
+| `roles.create` | 创建角色 | namespace、code、name | 角色对象 |
+| `roles.list` | 查询角色 | namespace、page、limit | { list, totalCount } |
+| `roles.assign` | 分配角色 | namespace、code、targets | 操作结果 |
+| `resources.create` | 定义资源及动作 | namespace、code、type、actions；API 资源使用 apiIdentifier | 资源对象 |
+| `permissions.authorize` | 授予资源权限 | namespace、list | 操作结果 |
+| `permissions.isAllowed` | 判断用户权限 | namespace、userId、resource、action | { allowed } |
+
+角色、资源和授权使用同一 `namespace`。创建资源用 `type`，授权资源项用 `resourceType`。
+
+## 应用管理
+
+```ts
+const { data: application } = await qoni.genauth.applications.create({
+  appName: 'Example app',
+  appIdentifier: 'example-app',
+  appType: 'web',
+  defaultProtocol: 'oidc',
+  redirectUris: ['https://app.example.com/callback'],
+})
+const { data: appDetails } = await qoni.genauth.applications.get({ appId: application.appId })
+const { data: appPage } = await qoni.genauth.applications.list({ page: 1, limit: 20 })
+```
+
+| 方法 | 功能 | 主要参数 | `data` |
+| --- | --- | --- | --- |
+| `applications.create` | 创建应用 | appName；自建应用传 appIdentifier，可设置 appType、defaultProtocol、redirectUris | 应用创建结果 |
+| `applications.get` | 读取应用配置 | appId | 应用对象 |
+| `applications.list` | 分页查询应用 | page、limit、keywords | 应用列表 |
+| `applications.update` | 更新应用配置 | appId 与更新字段 | 应用对象 |
+| `applications.delete` | 删除应用 | appId | 操作结果 |
+
+## 自定义字段
+
+```ts
+await qoni.genauth.customFields.set({
+  list: [{ targetType: 'USER', key: 'costCenter', label: 'Cost center', dataType: 'STRING' }],
+})
+await qoni.genauth.customFields.setData({
+  targetType: 'USER', targetIdentifier: user.userId,
+  list: [{ key: 'costCenter', value: 'engineering' }],
+})
+const { data: fieldValues } = await qoni.genauth.customFields.getData({
+  targetType: 'USER', targetIdentifier: user.userId,
+})
+```
+
+| 方法 | 功能 | 主要参数 | `data` |
+| --- | --- | --- | --- |
+| `customFields.list` | 查询字段定义 | targetType，默认 USER | 字段定义列表 |
+| `customFields.set` | 创建或更新字段定义 | list: { targetType, key, label, dataType }[] | 操作结果 |
+| `customFields.setData` | 设置对象字段值 | targetType、targetIdentifier、list | 操作结果 |
+| `customFields.getData` | 读取对象字段值 | targetType、targetIdentifier | 字段数据 |
+
+先定义字段，再写入字段值。已有字段的 `dataType` 不能修改；角色字段需要传所属 `namespace`。
+
+## 其他管理功能
+
+| 入口 | 功能 |
+| --- | --- |
+| `tenants` | 租户与租户成员 |
+| `identityProviders` | 外部身份源与连接配置 |
+| `dataPermissions / policies` | 数据资源、策略及数据授权 |
+| `auditLogs / sessions` | 管理审计与用户会话 |
+| `security / whitelist / riskLists` | MFA、安全设置及访问名单 |
+| `webhooks / events` | Webhook 配置与事件 |
+| `sync / pipelines` | 账号同步及认证流程 |
+| `accessKeys` | 访问密钥管理 |
+| `positions / dynamicGroups` | 岗位与动态用户组 |
+| `devices / deviceRules` | 设备及设备规则 |
+| `publicAccounts / invitations` | 公共账号及邀请 |
+| `approvals / ldap` | 审批与 LDAP 配置 |
+| `metadata / email / billing` | 元数据、邮件及计费配置 |
+
+以上入口均位于 `qoni.genauth` 下。具体方法、参数与返回类型见 [管理方法参考](./genauth-management-api)。
+
+## 返回值与请求取消
+
+```ts
+const controller = new AbortController()
+const { data: rolePage, meta } = await qoni.genauth.roles.list(
+  { namespace: 'project', page: 1, limit: 20 },
+  { signal: controller.signal },
+)
+console.log(rolePage.list, meta.requestId)
+```
+
+方法返回 `Promise<QoniResponse<T>>`：`data` 为业务结果，`meta.requestId` 为请求标识。第二参数传 `{ signal }`，调用 `controller.abort()` 取消请求。`users.iterate` 返回 `AsyncIterable`。
+
+## 使用已有管理 Token
+
+```ts
+const { data: roleList } = await qoni.genauth.roles.list({
+  namespace: 'project',
+  adminToken: process.env.GENAUTH_MANAGEMENT_TOKEN!,
+  userPoolId: process.env.GENAUTH_USER_POOL_ID!,
+})
+```
+
+`adminToken` 与 `userPoolId` 必须同时传入。显式传入的 Token 过期后由调用方更新。
+
+## 错误处理
+
+```ts
+import { QoniError } from '@qoniai/qoni'
+
+try {
+  await qoni.genauth.users.get({ userId: '<user-id>' })
+} catch (error) {
+  if (error instanceof QoniError) {
+    console.error(error.code, error.message, error.requestId)
+  }
+  throw error
+}
+```
+
+| 错误 | 处理方式 |
+| --- | --- |
+| `QoniValidationError` | 检查必填参数与字段类型 |
+| `401` / `403` | 检查凭据、用户池绑定及管理权限 |
+| `404` | 检查对象 ID 与所属用户池 |
+| `409` | 处理对象状态冲突或标识重复 |
+| `QoniTimeoutError` | 重试写操作前先查询原操作结果 |
+| 其他 `QoniError` | 查看 `code`、`message`、`requestId`、`body` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qoniai/qoni",
-  "version": "0.8.0",
-  "description": "Unified Node.js SDK for Qoni Agent delegation, GUMem memory, and WebAgent automation.",
+  "version": "0.9.1",
+  "description": "Unified Node.js SDK for Qoni Agent delegation, GenAuth management, GUMem memory, and WebAgent automation.",
   "homepage": "https://github.com/QONIAI/qoni-sdk-node#readme",
   "bugs": {
     "url": "https://github.com/QONIAI/qoni-sdk-node/issues"
@@ -19,7 +19,10 @@
     "sdk",
     "delegation",
     "gumem",
-    "webagent"
+    "webagent",
+    "genauth",
+    "authing",
+    "management"
   ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -46,7 +49,7 @@
     "gen:event-types": "node scripts/gen-event-types.mjs",
     "typecheck": "tsc --noEmit",
     "test": "pnpm build && pnpm check:brand && pnpm test:mock && pnpm test:package",
-    "test:mock": "vitest run --coverage=false tests/qoni.test.ts tests/semantic-surface.test.ts tests/open-source-readiness.test.ts tests/complete-coverage.test.ts tests/event-catalog.test.ts tests/interactions.test.ts tests/contract-surface.test.ts tests/sse-abort.test.ts tests/do-anything-evidence.test.ts tests/query-matrix.test.ts tests/live-evidence.test.ts tests/site-login-settle-track.test.ts",
+    "test:mock": "vitest run --coverage=false tests/qoni.test.ts tests/semantic-surface.test.ts tests/open-source-readiness.test.ts tests/complete-coverage.test.ts tests/event-catalog.test.ts tests/interactions.test.ts tests/contract-surface.test.ts tests/sse-abort.test.ts tests/do-anything-evidence.test.ts tests/query-matrix.test.ts tests/live-evidence.test.ts tests/site-login-settle-track.test.ts tests/abstract-interactions.test.ts tests/genauth-management.test.ts tests/genauth-communication.test.ts tests/genauth-hosted-login.test.ts tests/personal-agent-page.test.ts tests/agent-provisioning.test.ts tests/formal-agent-silent.test.ts tests/formal-agent-wildcard.test.ts tests/delegation-normalizer-r3.test.ts tests/gray-track-contract.test.ts",
     "test:e2e": "QONI_LIVE_E2E=1 vitest run --coverage=false --fileParallelism=false --maxWorkers=1 --testTimeout=120000 tests/live-e2e/*.test.ts",
     "test:e2e:do-anything": "QONI_LIVE_E2E=1 vitest run --coverage=false --fileParallelism=false --maxWorkers=1 --testTimeout=120000 tests/live-e2e/do-anything.test.ts",
     "test:e2e:do-anything:release": "QONI_LIVE_E2E=1 QONI_LIVE_ALLOW_ENV_CONSTRAINTS=0 vitest run --coverage=false --fileParallelism=false --maxWorkers=1 --testTimeout=120000 tests/live-e2e/do-anything.test.ts",
@@ -58,7 +61,13 @@
     "smoke:auth-gum:live": "pnpm build && QONI_SMOKE_MODE=live node scripts/qoni-auth-gum-smoke.mjs --live",
     "pack:dry-run": "pnpm build && pnpm pack --dry-run",
     "prepack": "pnpm build",
-    "prepare": "tsup"
+    "prepare": "tsup",
+    "gen:genauth-management": "node scripts/gen-genauth-management.mjs",
+    "test:e2e:genauth": "QONI_LIVE_E2E=1 vitest run --coverage=false --fileParallelism=false --maxWorkers=1 --testTimeout=30000 tests/live-e2e/genauth-management.test.ts",
+    "gen:genauth-communication": "node scripts/gen-genauth-communication.mjs",
+    "check:genauth-communication": "node scripts/gen-genauth-communication.mjs --check",
+    "test:e2e:communication": "QONI_LIVE_E2E=1 vitest run --coverage=false --fileParallelism=false --maxWorkers=1 --testTimeout=30000 tests/live-e2e/genauth-communication.test.ts",
+    "check:genauth-communication-examples": "node scripts/check-genauth-communication-examples.mjs"
   },
   "publishConfig": {
     "access": "public"

package/skills/qoni-sdk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qoni-sdk
-description: Use when building, testing, debugging, or documenting Node.js integrations with @qoniai/qoni, the Qoni constructor, AK/SK credentials, delegateToken, GenAuth currentUser/userInfo/introspection/user management, Qoni runtime-config discovery, GUMem, WebAgent, Web Search, Do Anything, Deep Research, Track, OBO product token exchange, or local .genauth.localhost SDK flows.
+description: Use when building, testing, debugging, or documenting Node.js integrations with @qoniai/qoni, the Qoni constructor, AK/SK credentials, delegateToken, GenAuth currentUser/userInfo/introspection/Authing v3 management, Qoni runtime-config discovery, GUMem, WebAgent, Web Search, Do Anything, Deep Research, Track, OBO product token exchange, or local .genauth.localhost SDK flows.
 ---
 
 # Qoni SDK
@@ -8,14 +8,14 @@ description: Use when building, testing, debugging, or documenting Node.js integ
 > **Requires `@qoniai/qoni` ≥ 0.4.0.** This guide documents the semantic-layer
 > surface: `run()`/`create()` return handles (`RunHandle` / `MonitorHandle`),
 > events are normalized (`event.type`, camelCase `data`, decoded screenshots),
-> and the 1:1 wire methods live under `qoni.<product>.api.*`. If the consumer
+> and supported 1:1 wire methods live under `qoni.<product>.api.*`. If the consumer
 > resolves an older version from npm, install this repo's local build instead
 > (`npm install <path-to-qoni-sdk-node>` or a `pnpm pack` tarball) — otherwise
 > the code below will not match the installed SDK.
 
 ## Core Contract
 
-Use `@qoniai/qoni` from trusted server-side Node.js code. Keep AK/SK on the server and create one reusable `Qoni`. For silent runtime product calls, resolve a real GenAuth user id from the credential-bound userpool, call `delegateToken`, then pass `delegation.data.token` explicitly to every product capability call. For interactive runtime authorization, call `delegateToken({ mode: "interactive", redirectUri, state, agent, scopes })` from the server without exposing AK/SK; redirect the user to `authorizationUrl`, then handle the business callback server-side with `completeDelegateToken({ grantId, code, state })` to receive the token. For GenAuth user management, call `qoni.genauth.users.*`; the SDK exchanges AK/SK for a standard GenAuth management token internally and does not require `QONI_USER_ID`.
+Use `@qoniai/qoni` from trusted server-side Node.js code. Keep AK/SK on the server and create one reusable `Qoni`. For silent runtime product calls, resolve a real GenAuth user id from the credential-bound userpool, call `delegateToken`, then pass `delegation.data.token` explicitly to every product capability call. For interactive runtime authorization, call `delegateToken({ mode: "interactive", redirectUri, state, agent, scopes })` from the server without exposing AK/SK; redirect the user to `authorizationUrl`, then handle the business callback server-side with `completeDelegateToken({ grantId, code, state })` to receive the token. For GenAuth management, use `qoni.genauth` domain namespaces (such as `users`, `roles`, `groups`, `organizations`, `applications`) or the Authing-name migration entry `qoni.genauth.management`; the SDK exchanges AK/SK for a standard GenAuth management token internally and does not require `QONI_USER_ID`.
 
 ```ts
 import { Qoni, QoniScopes } from "@qoniai/qoni";
@@ -66,12 +66,12 @@ const run = await qoni.doAnything.run({
 });
 const result = await run.wait({
   onScreenshot: (img, i) => saveImage(`step-${i}.jpg`, img.bytes),
-  onInputRequest: (req) => openForUser(req.liveUrl),
+  onInteraction: (handle) => handleInteraction(handle), // see "Do Anything Interactions"
 });
 console.log(result.output);
 ```
 
-For explicit authorization, the Qoni Console/BFF owns GenAuth login and grant completion before it redirects back to the business `redirectUri`. The redirect only carries one-time callback fields such as `code`, `state`, and `grant_state`/`grantId`; never design an API that exposes a delegation token to browser code.
+For explicit authorization, the Qoni Console/BFF owns GenAuth login and grant completion before it redirects back to the business `redirectUri`. The redirect only carries one-time callback fields: `code`, `grant_state`, and your business `state` when you supplied one. It does not carry `grantId`; load the `grantId` you saved by `grant_state`. Never design an API that exposes a delegation token to browser code.
 
 ```ts
 const grant = await qoni.delegateToken({
@@ -82,12 +82,17 @@ const grant = await qoni.delegateToken({
   scopes: [QoniScopes.GUMEM_MEMORY_READ],
 });
 
+// The callback carries code, state (your business state) and grant_state, but no grantId.
+await savePendingGrant(grant.data.grantState, { grantId: grant.data.grantId, businessState: "business-csrf-state" });
 redirectUserTo(grant.data.authorizationUrl);
 
+// Callback handler: look up by grant_state, check the business state, then exchange.
+const pending = await loadPendingGrant(callback.grant_state);
+if (!pending || callback.state !== pending.businessState) throw new Error("Invalid delegation callback");
 const completed = await qoni.completeDelegateToken({
-  grantId,
-  code,
-  state,
+  grantId: pending.grantId,
+  code: callback.code,
+  state: callback.grant_state,
 });
 ```
 
@@ -148,7 +153,7 @@ const run = await qoni.doAnything.run({
 run.id;
 run.sessionRef;                            // pass back to run({ session })
 await run.status();                        // refresh current state
-await run.respond(requestId, response?);   // HITL answer; omit response to skip
+run.interactionHandle(event.data);         // wrap an interaction event; answer via its methods
 await run.cancel(reason?);                 // idempotent — safe on a finished run
 
 const result = await run.wait({
@@ -156,7 +161,7 @@ const result = await run.wait({
   onEvent: (e) => console.log(e.type),
   onWireEvent: (e) => appendRawEvidence(e), // every SSE frame before semantic filtering
   onReconnect: (info) => logReconnect(info.attempt, info.lastEventId),
-  onInputRequest: (req) => openForUser(req.liveUrl),
+  onInteraction: (handle) => handleInteraction(handle), // typed InteractionHandle
   onScreenshot: (img, i) => saveImage(`step-${i}.jpg`, img.bytes),
 });
 // result: { runId, status: "succeeded"|"failed"|"canceled", output?, artifacts,
@@ -210,18 +215,133 @@ for await (const event of run.events()) {
 
 `qoni.doAnything.api.events({ token, sessionId, runId, signal?, lastEventId?, onlyTopLevel? })` yields raw `{ id?, event, data }` wire events: the type is a raw string on `event.event` (e.g. `"run.status_changed"`), the payload is `event.data.data` (snake_case), and `event.data.task_id` identifies the run. `run.status_changed` payloads carry the new status in `.to` (NOT `.status`). Terminal detection is `event.event === "run.completed"`. Wire names are internal and may evolve — prefer the high-level `run.events()` + `event.type` instead.
 
-## Do Anything Login Wall (human handoff)
+## Track and deprecated snapshot reads
+
+Use `track.create({ token, prompt, schedule, title? })` with an explicit
+`{ kind: "interval", intervalSeconds: N }` (integer 600–2592000 seconds) or
+`{ kind: "daily", at: "HH:MM", tz: "Area/City" }`. Daily starts 0–30 minutes
+before the target. Prompt maps to instructions; include URLs there. No default
+schedule is inferred, and arbitrary cron is rejected with a daily alternative.
+
+The historical `MonitorHandle` name remains. `get()` normalizes the real Track
+record: known schedule shapes convert without write-bound/Intl revalidation;
+unknown/incomplete wire schedules stay verbatim. Input validation remains strict.
+`pause()`/`resume()` PATCH status; pause keeps any started check running.
+`refine()` accepts title/schedule only and cannot change instructions.
+`runNow()` returns `{ trackId, sessionId, runId }` (202 acceptance); it can
+surface 409 task_in_progress. `runs({ limit?, offset? })` slices the newest 50
+checks locally; `run(id)` searches that exact window and reports its range on
+not_found. Keep real status/outcome/headline/answer/failure, never invent
+extracted/diffs/snapshotId. `delete()` soft-deletes without cancelling a running task.
+
+Create starts a first_look immediately. Capture the original initial lastTaskId,
+wait for that exact check to terminate, then call runNow once; never retry 409
+implicitly or substitute another check. Checks keep `running/done/failed/expired/
+canceled`; success is done, distinct from RunResult.status succeeded. A missing
+check in the recent window is local not_found without an HTTP status; a missing
+Track is backend 404 track_not_found.
+
+The example uses the reusable qoni client and delegated token from Core Contract:
 
-A web task often hits a page only the end user can log in to. The agent parks and emits an **`inputRequest`** event. The live-browser URL arrives on the request payload (`event.data.liveUrl`; live-url changes also stream as `progress` events with `data.liveUrl`). The client's ONLY job is to surface that URL so the human can sign in — login detection is the BACKEND's job; it re-probes and resumes the run automatically.
+```ts
+import type { MonitorSchedule } from "@qoniai/qoni";
+
+const monitor = await qoni.track.create({
+  token,
+  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 });
+
+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`);
+}
+
+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
+}
+```
 
-- Open `liveUrl` ONCE in a real browser when you see `inputRequest`. Do NOT poll, do NOT call `respond`, do NOT wait on the window closing.
-- Keep iterating (or stay inside `wait()`); the run progresses past the wall and reaches its terminal event on its own once the user is signed in.
-- The first login is unavoidable; later runs reuse persisted login state and never reach this wall.
+Wire API mapping (all supported routes use `/track/tracks`, not `/monitors`):
+
+| Method | Contract |
+| --- | --- |
+| createMonitor / getMonitor | POST / GET Track; create uses instructions/title and wire schedule every_seconds or daily_at/tz. |
+| updateMonitor | PATCH title/instructions/schedule/status; raw instructions is supported, high-level refine is stricter. |
+| runNow / deleteMonitor | POST run_now returns track_id/session_id/run_id; DELETE returns empty 204. |
+| listRuns / getRun | GET checks, local pagination/exact lookup within the recent 50. |
+| api.events / api.intervene / MonitorHandle.events / interactionHandle | Deprecated; local QoniUnsupportedError, zero HTTP and zero token exchange. No Track scope authorizes DoAnything actions. |
+
+Legacy targetUrls/extractionSchema/triggerDsl/stopConditionDsl/notifyChannel
+(including snake_case) and url are unsupported local errors, never folded into
+instructions. Cron and legacy event/option types remain exported, deprecated.
+Invalid or missing input schedules raise QoniValidationError before HTTP.
+Optional undefined keys keep their original omission behavior; defined
+unsupported values (including null) are still local errors. Interval tz, when
+specified, is an invalid schedule and raises QoniValidationError.
+
+`doAnything.api.readArtifacts` and DoAnythingSnapshot/SnapshotImage/SnapshotAction
+are deprecated: no backend snapshot route/source exists. The method raises
+local QoniUnsupportedError (`unsupported.operation`), zero HTTP. Read actual
+files with `qoni.doAnything.artifacts({ token, runId })` / api.listArtifacts and download via
+artifact.content()/api.artifactDownloadUrl. For images, enable
+capture.screenshots and consume screenshot events. A text artifact is not a
+snapshot. Deprecated unsupported negatives never count as positive capability coverage.
+
+## Do Anything Interactions (human handoff)
+
+When a run needs the user it pauses and emits one `interaction` event per request (`event.data` is a typed `Interaction`; `wait({ onInteraction })` hands you an `InteractionHandle`). Interactions are typed by what the user must do, never by business: `site_login`, `take_control`, `ask_user`, `confirmation`, plus the system `wait`. `switch (handle.interaction.type)` narrows `payload` per branch.
+
+- Act only on `status === "pending"` and dedupe by `interaction.id`: creation, status changes and reconnect replays all call back again with the same `id` and `type`. Updates with real content replace the card (an `active` take-over carries a new `liveUrl`); only empty settling shells keep the original `payload`.
+- Interactions arrive one at a time; the run resumes once the current one is handled.
+- `site_login`: `openLogin()` → show `liveUrl` → after the user signs in, `confirmSignedIn()` (it saves the login once, then the agent rechecks). Do NOT call the deprecated `login.confirm()` first. A `QoniError` coded `site_login.save_failed` or `site_login.session_replaced` is retryable: call `confirmSignedIn()` again. Delegate `webagent.site_login:request` and `webagent.site_login:confirm`.
+- `ask_user`: `answer(value)` with the type `payload.answerType` names (`text` string, `number`, `boolean`, `single_choice` option value, `multiple_choice` array of option values), or `skip()`. The wire's `clarification` arrives as `ask_user`; never switch on `"clarification"`.
+- `take_control`: `connectControl()` only when `handle.can("connect_control")`; it resolves to `{ liveUrl, expiresAt }` (show that URL, else `payload.liveUrl`) → `releaseControl()`. `refreshControl()` returns a fresh URL.
+- `confirmation`: `confirm()` or `reject()` after showing `payload.summary`.
+- Only call methods `handle.can(kind)` reports; an undeclared action throws.
 
 ```ts
 const result = await run.wait({
-  onInputRequest: (req) => {
-    if (req.liveUrl) openBrowserForUser(String(req.liveUrl)); // pop once; the backend resumes by itself
+  onInteraction: async (handle) => {
+    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();
+        await showToUser(login.liveUrl);       // resolves when the user says "I'm signed in"
+        await handle.confirmSignedIn();
+        break;
+      }
+      case "ask_user":
+        await handle.answer(await askUser(request.payload));
+        break;
+      case "confirmation":
+        await handle.confirm();
+        break;
+    }
   },
 });
 ```
@@ -243,12 +363,9 @@ pending → running → (running ⇄ awaiting_input)* → succeeded | failed | c
   `terminal_reason` / `is_task_successful`).
 
 **Client action is event-driven, not status-driven.** The only thing that needs
-you is the `inputRequest` event (surface `liveUrl` so a human can log in /
-confirm — see Login Wall). Everything else, including login walls, the backend
-re-probes and resumes on its own. A run flapping `running ⇄ awaiting_input`
-(e.g. `waiting_reason=confirmation_required` during internal pacing) is
-expected — do NOT poll or call `respond`. Only call `respond` to answer an
-actual `inputRequest`.
+you is an `interaction` event (see Do Anything Interactions). A run flapping
+`running ⇄ awaiting_input` (e.g. `waiting_reason=confirmation_required` during
+internal pacing) is expected — do NOT poll; act only on pending interactions.
 
 ### Parent & sub-tasks
 
@@ -322,3 +439,19 @@ For skill or docs changes that teach integration, also validate from a fresh con
 5. Run the consumer project's typecheck and test command.
 
 Prefer mocked fetch-based tests for normal verification. Use real GenAuth/GUMem/WebAgent services only for explicit smoke tests, and never hard-code real secrets in repository files.
+
+## Authing v3 management additions
+
+The SDK provides 591 typed JSON management methods in 35 namespaces, aligned with the official Authing Node SDK 4.0.2 (496 JSON methods) plus GenAuth extensions and compatibility names. Read `docs/genauth-management.md` and `docs/genauth-management-api.md` for exact methods, aliases, inputs and deployment-dependent rules. Preserve the Qoni management-token exchange; do not use a delegated runtime token for management calls.
+
+- Use `genauth.users.iterate` for paginated user processing (limit 1-50); pass cancellation in the optional second argument.
+- Roles and resources belong to an existing permission namespace. Resource action names use `resourceCode:action`; newer permission deployments require `apiIdentifier` for API resources.
+- `customFields.set` requires `dataType` for both create and update. `customFields.list` defaults the subject to `USER`.
+- HTTP-200 business errors throw typed Qoni errors, including numeric Authing API codes as strings. Do not replay writes after network or business failures.
+- Respect employment rules: resign a user only when departure is intended. The SDK never automatically resigns users to make deletion succeed.
+- Filtered user queries depend on the GenAuth search index. A successful `get` or batch lookup does not prove that a newly created user is searchable. Keep search acceptance failures visible and diagnose the server index separately.
+- Run `pnpm test:e2e:genauth` using an isolated test userpool; cleanup failures fail the suite. Generated contract coverage does not imply live acceptance of every operation.
+
+### Agent Mail and Agent Phone (unreleased extension)
+
+Use `qoni.genauth.agentMail` and `qoni.genauth.agentPhone`. Read `docs/genauth-communication.md` and `docs/genauth-communication-api.md` before using these APIs. Runtime requires native GenAuth credentials through `genauthCommunicationCredentials`; administrator calls reuse Qoni management exchange. Preserve stable idempotency keys, pass current revisions, and inspect original operations after ambiguous results. Never treat an unknown purchase/send outcome as safe to repeat. Phone numbers, mailboxes, and communication personas are distinct from login email/phone and delegation agentId.