@qoniai/qoni 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -6,8 +6,65 @@ This project follows semantic versioning. Before `1.0.0`, minor versions may
 include SDK API changes, while patch versions are reserved for backward
 compatible fixes.
 
+## 0.4.2 - 2026-09-09
+
+### Fixed
+
+- Require authoritative run details when settling `wait()`: preserve detail
+  errors and reject unconfirmed terminal states instead of inventing success.
+- Reuse terminal details read after a clean stream close and resume from every
+  wire event cursor, including frames filtered from semantic events.
+- Propagate wait cancellation to detail and artifact-list GETs. Bound complete
+  JSON, NDJSON, binary, and HTTP error body reads by the request timeout, cancel
+  stalled readers, and discard late responses without starting replacement runs.
+- Clean up wait timers and SSE abort listeners. Cancel idle SSE readers directly
+  and release their locks without waiting indefinitely for source cancellation.
+- Retry HTTP 408 stream failures within the configured reconnect budget and stop
+  delivering buffered events after cancellation.
+
+### Added
+
+- Optional abort signals on product run-detail and artifact-list wire reads;
+  existing calls without a signal remain compatible.
+
 ## Unreleased
 
+### Breaking
+
+- Rename the public SDK constructor from its previous longer name to `Qoni`.
+  The previous constructor export has been removed.
+
+### Changed
+
+- The default Qoni host is now `https://dashboard.qoni.ai` (was
+  `https://anima.eazo.ai/dashboard`). Callers that never passed an explicit `host`
+  reach a different control plane after upgrading. Note that the new default has
+  no `/dashboard` path segment — pass `host` explicitly for private or local
+  deployments.
+- Service resolution no longer fetches the runtime-config document to answer a
+  Qoni base URL. It never read the result for that service, but it did require
+  the fetch to succeed, so an unavailable discovery endpoint failed every Qoni
+  call. Discovery is still fetched lazily for `genauth` / `gumem` / `webagent`,
+  which do read it.
+- Signed Qoni requests always stay on the configured control-plane host. Service
+  resolution no longer follows `eakBaseUrl` from the runtime config for the
+  Qoni service, because AK/SK signatures are scoped to that endpoint and a
+  cross-origin runtime URL can strip `Authorization` on redirect or disclose
+  credentials to an unintended origin.
+- `unstableRequest()` without a `token` now signs the call with AK/SK instead of
+  sending it unauthenticated. Caller-supplied `authorization`, `content-type`,
+  `date` and `x-authing-*` headers are dropped so they cannot corrupt the
+  signature.
+
+### Fixed
+
+- The previous default host was unreachable for SDK API calls. A client created
+  as `new Qoni({ accessKey, secretKey })` now reaches the live control plane.
+- Abandoning an event iterator no longer leaks its connection. Leaving
+  `for await (const event of run.events())` through a `break` now cancels the
+  response body before releasing the reader lock, returning the socket to the
+  connection pool.
+
 ### Added
 
 - `RunHandle.events()` and `wait()` accept `onWireEvent` and `onReconnect`
@@ -23,8 +80,8 @@ compatible fixes.
 ### Breaking
 
 - Rename the package from its previous product name to `@qoniai/qoni`.
-- Rename the primary constructor and all branded exports to `QoniAgentKit`,
-  `Qoni`, and the corresponding `Qoni*` types, constants, and error classes.
+- Rename the primary constructor and all branded exports to `Qoni` and the
+  corresponding `Qoni*` types, constants, and error classes.
 - Rename the product namespace to `client.qoni` and environment variables to
   `QONI_*`. The current server wire contract remains unchanged: SDK gateway
   routes stay under `/api/v3/eak/*`, delegation tokens retain
@@ -207,7 +264,7 @@ Initial public release of `@qoniai/qoni`.
 
 ### What ships
 
-- Server-side `QoniAgentKit` constructor for Qoni Agent delegation and product
+- Server-side `Qoni` constructor for Qoni Agent delegation and product
   runtime calls.
 - Runtime service discovery from the Qoni Console gateway through
   `GET /api/v3/eak/runtime-config`.
@@ -226,7 +283,7 @@ Initial public release of `@qoniai/qoni`.
 
 ### Compatibility
 
-- `Qoni` remains available as a short constructor alias.
+- `Qoni` is the public SDK constructor.
 - `delegateAgent` and `completeDelegateAgent` remain available as deprecated
   aliases for older integrations, but new integrations should use
   `delegateToken`.

package/README.md

@@ -19,7 +19,7 @@ Agents that perform real work need more than a backend API key. They need a user
 
 Qoni keeps that model small:
 
-- One SDK entry: `new QoniAgentKit({ accessKey, secretKey })`.
+- One SDK entry: `new Qoni({ accessKey, secretKey })`.
 - One discovery path: `host` can override the Qoni Console/SDK gateway for private or local deployments, and the SDK reads downstream runtime URLs from `/api/v3/eak/runtime-config`.
 - One delegation entry: call `delegateToken`; silent mode returns `data.token`, while interactive mode returns an authorization URL and later completes on your server.
 - One management path: call `genauth.users.*`, and the SDK exchanges AK/SK for a GenAuth management token before calling GenAuth v3 users APIs.
@@ -59,8 +59,8 @@ The package ships both ESM and CommonJS builds with TypeScript types, so either
 import style works:
 
 ```ts
-import { QoniAgentKit } from "@qoniai/qoni";        // ESM / TypeScript
-const { QoniAgentKit } = require("@qoniai/qoni");    // CommonJS
+import { Qoni } from "@qoniai/qoni";        // ESM / TypeScript
+const { Qoni } = require("@qoniai/qoni");    // CommonJS
 ```
 
 ## AI Skill
@@ -87,9 +87,9 @@ Start with a server-side SDK instance. AK/SK stays on your trusted server for bo
 
 ```ts
 import fs from "node:fs";
-import { QoniAgentKit } from "@qoniai/qoni";
+import { Qoni } from "@qoniai/qoni";
 
-const qoni = new QoniAgentKit({
+const qoni = new Qoni({
   accessKey: process.env.QONI_ACCESS_KEY!,
   secretKey: process.env.QONI_SECRET_KEY!,
 });
@@ -472,7 +472,7 @@ const sameMonitor = await qoni.track.attach(monitor.id, { token });
 ### GenAuth User Context and Management
 
 ```ts
-const client = new QoniAgentKit({
+const client = new Qoni({
   accessKey: process.env.QONI_ACCESS_KEY!,
   secretKey: process.env.QONI_SECRET_KEY!,
 });
@@ -499,7 +499,7 @@ const created = await client.genauth.users.create({
 ### Client
 
 ```ts
-const qoni = new QoniAgentKit({
+const qoni = new Qoni({
   accessKey: process.env.QONI_ACCESS_KEY!,
   secretKey: process.env.QONI_SECRET_KEY!,
   timeoutMs: 30_000,
@@ -512,7 +512,7 @@ const qoni = new QoniAgentKit({
 | `secretKey` | `string` | Yes | Qoni secret key from Qoni Console. |
 | `host` | `string` | No | Optional Qoni Console/SDK gateway override for private or local deployments. |
 | `fetch` | `typeof fetch` | No | Custom transport implementation. |
-| `timeoutMs` | `number` | No | Per-request timeout (connect + response headers). Defaults to `30000`. |
+| `timeoutMs` | `number` | No | Per-request timeout (connect + headers + body for one-shot requests; headers only for successful SSE connections). Defaults to `30000`. |
 
 > **`timeoutMs` does not bound a long-running run.** It applies to individual
 > one-shot HTTP requests (delegation, `status()`, a single POST). The live
@@ -524,12 +524,6 @@ const qoni = new QoniAgentKit({
 > `wait()` timeout does not stop the run; it keeps executing server-side and
 > you can `attach()` to it again.
 
-`Qoni` is also exported as a short alias:
-
-```ts
-import { Qoni, QoniAgentKit } from "@qoniai/qoni";
-```
-
 ### Namespaces
 
 | Namespace | Methods |
@@ -556,6 +550,26 @@ await run.cancel(reason?)               // idempotent
 
 `await run.wait(...)` settles to a `RunResult`:
 
+The run-detail response must confirm a terminal state. Detail read errors propagate
+unchanged; `wait()` never substitutes an SSE completion payload for the authoritative
+result. A nonterminal or incomplete detail rejects with a retryable `upstream.failed`
+error; use `status()` or re-attach to recover.
+
+`timeoutMs` and `signal` stop waiting for detail/artifact reads and promises returned
+by `onEvent`, `onWireEvent`, `onInteraction`, and `onScreenshot`. They cannot preempt
+synchronous JavaScript or stop work already started inside a callback. `onReconnect`
+is synchronous telemetry: its return value is not awaited and returned promise
+rejections are not handled. Do not pass an async callback there; synchronous throws
+propagate. Reconnect backoff remains abortable and subject to the wait deadline.
+
+Detail/artifact-list GETs receive the wait signal: aborting or timing out a wait aborts
+the request and cancels its body reader. The client's per-request timer also covers
+complete JSON/NDJSON and binary body reads, including HTTP error bodies. A late response
+from a custom fetch that ignores abort has its body canceled and cannot resume settlement
+or start subsequent run requests. Custom transports must honor `RequestInit.signal` to
+stop their own in-flight network work. Stopping a wait neither cancels the server-side
+run nor creates a replacement task; use `cancel()` explicitly to stop the existing run.
+
 ```ts
 interface RunResult {
   runId: string;

package/README.zh-CN.md

@@ -14,7 +14,7 @@ AK/SK 必须只保存在可信服务端，不能下发到浏览器、移动端
 
 Qoni 把 Agent 授权模型收敛成几个稳定边界：
 
-- 一个 SDK 入口：`new QoniAgentKit({ accessKey, secretKey })`。
+- 一个 SDK 入口：`new Qoni({ accessKey, secretKey })`。
 - 一条发现路径：`host` 可在私有化或本地部署中覆盖 Qoni Console/SDK 网关，SDK 通过 `/api/v3/eak/runtime-config` 获取 GenAuth、GUMem、WebAgent 等运行时地址。
 - 一个授权入口：调用 `delegateToken`；silent 模式直接返回 `data.token`，interactive 模式返回授权 URL，之后由业务服务端完成兑换。
 - 一条管理面路径：调用 `genauth.users.*`，SDK 会先用 AK/SK 换取 GenAuth management token，再调用 GenAuth v3 users API。
@@ -52,8 +52,8 @@ yarn add @qoniai/qoni
 包同时发布 ESM 和 CommonJS 两套构建（都带 TypeScript 类型），两种引入方式都可用：
 
 ```ts
-import { QoniAgentKit } from "@qoniai/qoni";        // ESM / TypeScript
-const { QoniAgentKit } = require("@qoniai/qoni");    // CommonJS
+import { Qoni } from "@qoniai/qoni";        // ESM / TypeScript
+const { Qoni } = require("@qoniai/qoni");    // CommonJS
 ```
 
 ## AI Skill
@@ -80,9 +80,9 @@ npm 包中包含 `skills/` 目录，但推荐仍使用上面的 GitHub 仓库安
 
 ```ts
 import fs from "node:fs";
-import { QoniAgentKit } from "@qoniai/qoni";
+import { Qoni } from "@qoniai/qoni";
 
-const qoni = new QoniAgentKit({
+const qoni = new Qoni({
   accessKey: process.env.QONI_ACCESS_KEY!,
   secretKey: process.env.QONI_SECRET_KEY!,
 });
@@ -442,7 +442,7 @@ const sameMonitor = await qoni.track.attach(monitor.id, { token });
 ### GenAuth 用户上下文与用户管理
 
 ```ts
-const client = new QoniAgentKit({
+const client = new Qoni({
   accessKey: process.env.QONI_ACCESS_KEY!,
   secretKey: process.env.QONI_SECRET_KEY!,
 });
@@ -469,7 +469,7 @@ const created = await client.genauth.users.create({
 ### Client
 
 ```ts
-const qoni = new QoniAgentKit({
+const qoni = new Qoni({
   accessKey: process.env.QONI_ACCESS_KEY!,
   secretKey: process.env.QONI_SECRET_KEY!,
   timeoutMs: 30_000,
@@ -482,16 +482,10 @@ const qoni = new QoniAgentKit({
 | `secretKey` | `string` | 是 | Qoni Console 创建的 secret key。 |
 | `host` | `string` | 否 | 私有化或本地部署时可选的 Qoni Console/SDK 网关覆盖地址。 |
 | `fetch` | `typeof fetch` | 否 | 自定义传输实现。 |
-| `timeoutMs` | `number` | 否 | 单次请求超时（连接 + 响应头），默认 `30000`。 |
+| `timeoutMs` | `number` | 否 | 单次请求超时（一次性请求覆盖连接、响应头及响应体；成功建立的 SSE 仅覆盖到响应头），默认 `30000`。 |
 
 > **`timeoutMs` 不会限制长任务。** 它只作用于单次一次性 HTTP 请求（委托、`status()`、单个 POST）。事件流（`events()` / `wait()`）**不受它约束**——流的响应头一到，这个单次计时器就被清掉了,所以一个跑一小时的 Deep Research 在默认 30s 客户端超时下也能正常流式。要限制等待时长用 `wait({ timeoutMs })`；不传则 `wait()` 一直等到终态。`wait()` 超时**不会停止 run**——它在服务端继续跑，可以再 `attach()` 回去。
 
-兼容导出：
-
-```ts
-import { Qoni, QoniAgentKit } from "@qoniai/qoni";
-```
-
 ### 命名空间
 
 | 命名空间 | 方法 |
@@ -518,6 +512,19 @@ await run.cancel(reason?)               // 幂等
 
 `await run.wait(...)` 结算成一个 `RunResult`：
 
+必须由 run-detail 响应确认终态。详情读取错误原样抛出，`wait()` 不会用 SSE 完成事件替代权威结果。
+详情仍为非终态或缺少终态信息时，抛出可重试的 `upstream.failed`；可通过 `status()` 或重新 `attach()` 恢复。
+
+`timeoutMs` 与 `signal` 会结束详情、交付物读取及 `onEvent`、`onWireEvent`、`onInteraction`、
+`onScreenshot` 返回的 Promise 的等待，但不能抢占同步 JavaScript，也不能停止回调内部已启动的工作。
+`onReconnect` 是同步遥测通知：返回值不被等待，返回的 Promise 的 rejection 也不被处理，因此不要传 async
+回调；同步抛错会向上传播。重连退避等待仍可被 signal 或 wait 超时中断。
+
+详情/交付物列表 GET 会接收 wait signal：wait 中止或超时时会中止请求、取消并释放响应体 reader。
+客户端单次请求计时器也覆盖完整 JSON/NDJSON、二进制响应体及 HTTP 错误体读取。即使自定义 fetch 忽略
+abort，SDK 也会取消其迟到响应体，不恢复结算或启动后续 run 请求；自定义传输须遵守 `RequestInit.signal`
+才能停止其内部网络工作。停止 wait 既不会取消服务端 run，也不会创建替代任务；需要停止原 run 时须显式调用 `cancel()`。
+
 ```ts
 interface RunResult {
   runId: string;