@zoowork-ai/sdk 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -3,6 +3,72 @@
 All notable changes to `@zoowork-ai/sdk` (formerly `@zooclaw-agents/sdk`). Dates are the
 day the behaviour was verified, not the day it was written.
 
+## 0.5.1 — 2026-08-31
+
+### Added
+
+- **`ZooworkError` keeps the evidence: `contentType`, `bodySnippet`, `cfRay`, `requestId`,
+  `retryable`.** A production `postEvents` failure surfaced as `HTTP 502, type: undefined`
+  and cost the reporter a day of black-box contrast experiments (2026-08-30,
+  `notes/probes/system-message-cold-session-probe.mts`): the edge replaces an origin 502/504
+  body wholesale with a branded `text/html` page, so no JSON envelope ever reaches the SDK —
+  and 0.5.0 then dropped the only three facts that survived. Now every transport error keeps
+  the response `Content-Type`, the first 600 characters of the raw body, and the `cf-ray`
+  header (present on JSON errors too, verified 2026-08-31) — the id to quote when reporting
+  a gateway failure. `requestId` reads `request_id` from either error envelope once the
+  server starts sending one; today it is usually absent. `retryable` is a transport-class
+  hint (`408/429/502/503/504`): it says the failure class tends to pass, not that a replay
+  is safe — pair it with `idempotency_key` before looping on it.
+  SDK-synthesized wait timeouts keep `retryable: false`: they report that the caller's own
+  polling budget expired, not that an HTTP 408 came back from the service.
+
+### Changed
+
+- **The fallback error message names what actually came back.** A non-JSON error body used
+  to read a bare `HTTP 502`; it now reads
+  `HTTP 502 (text/html; charset=UTF-8) [cf-ray a338c539…]`. Messages parsed from a server
+  envelope are unchanged — keep matching on `type`/`status`, never on message text.
+- **`streamEvents` raises the same enriched envelope** on a non-ok response instead of the
+  bare `events stream HTTP <status>` string, so SSE failures are diagnosable the same way.
+- **A structured `detail` object no longer stringifies into the message.** The agents-family
+  envelope may carry `detail` as an object; it previously became the literal message
+  `[object Object]`, now it falls through to the status line and stays readable in
+  `bodySnippet`.
+
+## 0.5.0 — 2026-08-28
+
+### Added
+
+- **The QR flow now covers WeCom and WeChat, not just Feishu** — gateway PR #3512 shipped
+  `/channels/{wecom,weixin}/{setup,poll,setup-cancel}`, and 0.4.x had no way to call them.
+  Four platform-taking methods replace the four Feishu-only ones:
+  `startChannelSetup(agentId, platform, input?)`, `pollChannelSetup`, `cancelChannelSetup`,
+  `waitForChannelSetup`. New types `ChannelSetupInput`, `ChannelSetupSession`,
+  `ChannelPollResult`, `GuidedSetupPlatform` (`'feishu' | 'wecom' | 'weixin'`) and
+  `AddChannelPlatform`.
+- **`startFeishuSetup` / `pollFeishuSetup` / `cancelFeishuSetup` / `waitForFeishuSetup` still
+  work** — they now delegate to the platform-taking versions. `FeishuSetupInput` and
+  `FeishuPollResult` are aliases of the new names; `FeishuSetupSession` narrows
+  `ChannelSetupSession` to the one platform that always answers `verification_uri_complete`.
+  Only the message text of a thrown timeout/abort changed (it names `waitForChannelSetup` and
+  the platform); `status` and `type` are unchanged.
+
+### Documentation
+
+- **`ChannelPlatform` gains `'weixin'`, and WeChat is no longer described as unbindable.**
+  0.3.2–0.4.2 said WeChat "answers `400 channel.weixin_setup_required`, naming a QR flow this
+  API does not expose". The flow exists now; that error is a signpost to it, not a dead end.
+  `addChannel` still refuses WeChat, so `AddChannelPlatform` is the type that lists what it
+  takes.
+- **Per-platform shapes, staging-verified 2026-08-28** (`notes/probes/channels-guided-probe.mts`):
+  Feishu answers `verification_uri_complete` + `poll_interval: 5`, `expires_in: 600`; WeCom and
+  WeChat answer `qrcode_url` with no `poll_interval` and `expires_in: 300`; WeChat's
+  `qrcode_url` may be an inline `data:image/…` payload rather than a URL. WeChat reads only
+  `dm_policy` and only `'open'`/`'disabled'` — `'allowlist'` is
+  `400 channel.allowlist_unsupported` — pins the account to `'default'`, and ignores anything
+  else in the body. Cancelled sessions 404 per platform:
+  `channel.{feishu,wecom,weixin}_session_not_found`.
+
 ## 0.4.2 — 2026-08-25
 
 ### Documentation

package/dist/client.d.ts

@@ -55,7 +55,39 @@ export declare class ZooworkError extends Error {
      * you only need the class of failure.
      */
     type?: string;
-    constructor(status: number, message: string, type?: string);
+    /**
+     * `Content-Type` of the error response. The field that tells an edge error page apart from an
+     * API answer: both envelopes above are `application/json`, while a gateway 502/504 arrives as
+     * `text/html` — the edge replaces the origin's body wholesale, so no JSON survives to parse
+     * (verified 2026-08-30 against both deployments;
+     * `notes/probes/system-message-cold-session-probe.mts`).
+     */
+    contentType?: string;
+    /** First {@link BODY_SNIPPET_LIMIT} characters of the raw error body, whatever it was.
+     * Without it a non-JSON failure cannot be reconstructed from `status` alone. */
+    bodySnippet?: string;
+    /**
+     * Cloudflare ray id (`cf-ray` response header), when the response crossed Cloudflare. It
+     * survives even the replaced-body case above — on an HTML 502 it is the only correlation id
+     * left, and the value to quote when reporting a gateway failure.
+     */
+    cfRay?: string;
+    /** Correlation id from the error envelope (`request_id` on either vocabulary), when the
+     * server includes one. Usually absent today. */
+    requestId?: string;
+    /**
+     * Transport-class transient hint: `true` for 408, 429, 502, 503 and 504. It says the failure
+     * CLASS tends to pass, not that a replay is safe — retrying a `postEvents` without an
+     * `idempotency_key` can still deliver twice. Pair it with idempotency keys before looping.
+     */
+    retryable: boolean;
+    constructor(status: number, message: string, type?: string, extra?: {
+        contentType?: string;
+        bodySnippet?: string;
+        cfRay?: string;
+        requestId?: string;
+        retryable?: boolean;
+    });
 }
 export interface Ownership {
     owner_uid: string;
@@ -259,22 +291,47 @@ export interface AgentChannel {
     [k: string]: unknown;
 }
 /**
- * The chat platforms you can bind, staging-verified 2026-08-25.
+ * The chat platforms you can bind, staging-verified 2026-08-28.
+ *
+ * Three of them have a server-driven QR flow ({@link GuidedSetupPlatform}); Slack does not,
+ * and structurally cannot — a Slack app is created by a person and its tokens only ever exist
+ * in that person's browser, so {@link AddChannelInput} with `botToken` + `appToken` is its
+ * permanent path.
+ *
+ * WeChat is the one platform that goes the other way: `'weixin'`/`'wechat'` on
+ * {@link ZooworkClient.addChannel} answers `400 channel.weixin_setup_required`, so the QR flow
+ * is its ONLY path. See {@link AddChannelPlatform}. Any name outside this type answers
+ * `400 channel.invalid_request`.
+ */
+export type ChannelPlatform = 'feishu' | 'slack' | 'wecom' | 'weixin';
+/**
+ * The platforms {@link ZooworkClient.addChannel} accepts — every {@link ChannelPlatform}
+ * except WeChat, which refuses explicit config and takes the QR flow only.
+ */
+export type AddChannelPlatform = 'feishu' | 'slack' | 'wecom';
+/**
+ * The platforms with a server-driven QR flow: {@link ZooworkClient.startChannelSetup} →
+ * render the URI → poll. Slack is absent by design, not by omission.
  *
- * Only `'feishu'` has a server-driven QR flow here, and the two reasons the others lack one
- * are different. Slack structurally cannot have one — a Slack app is created by a person, and
- * its tokens only ever exist in that person's browser — so `addChannel` with `botToken` +
- * `appToken` is its permanent path. WeCom's flow exists in the product but is not exposed on
- * this API yet, so today it also binds through `addChannel`.
+ * The three differ in what the setup answer carries and in what the body may say
+ * (staging-verified 2026-08-28):
  *
- * WeChat (`'weixin'`/`'wechat'`) is absent because it cannot be bound here at all: it answers
- * `400 channel.weixin_setup_required`, naming a QR flow this API does not expose. Any other
- * name answers `400 channel.invalid_request`.
+ * - `feishu` — answers `verification_uri_complete` and a `poll_interval`; takes `brand`,
+ *   `account`, `dm_policy`, `group_policy`; `expires_in: 600`.
+ * - `wecom` — answers `qrcode_url` and NO `poll_interval` (you pick the cadence); takes
+ *   `account`, `dm_policy`, `group_policy`; `expires_in: 300`.
+ * - `weixin` — answers `qrcode_url`, which may be a URL *or* an inline `data:image/…` payload;
+ *   takes `dm_policy` only, `'open'` or `'disabled'` (the account is pinned to `'default'` and
+ *   the group policy to `'disabled'` server-side); `expires_in: 300`.
  */
-export type ChannelPlatform = 'feishu' | 'slack' | 'wecom';
+export type GuidedSetupPlatform = 'feishu' | 'wecom' | 'weixin';
 export interface AddChannelInput {
-    /** See {@link ChannelPlatform}. Typed loosely so a newly supported platform needs no SDK release. */
-    platform: ChannelPlatform | (string & {});
+    /**
+     * See {@link AddChannelPlatform}. Typed loosely so a newly supported platform needs no SDK
+     * release. `'weixin'`/`'wechat'` is refused here with `400 channel.weixin_setup_required` —
+     * use {@link ZooworkClient.startChannelSetup} instead.
+     */
+    platform: AddChannelPlatform | (string & {});
     /**
      * Names this binding. It is part of the record's identity, not a setting: `updateChannel`
      * and `removeChannel` find a binding by `platform` + `account`, and nothing renames one
@@ -324,8 +381,14 @@ export interface UpdateChannelInput {
     group_policy?: string;
     enabled?: boolean;
 }
-export interface FeishuSetupInput {
-    /** `'feishu'` (default) or `'lark'` — the international brand of the same platform. */
+/**
+ * Body for {@link ZooworkClient.startChannelSetup}. Every field is optional, and each platform
+ * reads a different subset — see {@link GuidedSetupPlatform}. A field a platform does not read
+ * is ignored rather than rejected: `weixin` accepts an `account` in the body and still binds
+ * `'default'` (staging-verified 2026-08-28).
+ */
+export interface ChannelSetupInput {
+    /** Feishu only: `'feishu'` (default) or `'lark'` — the international brand of the same platform. */
     brand?: 'feishu' | 'lark';
     /**
      * Names this binding. It is part of the record's identity, not a setting: `updateChannel`
@@ -351,37 +414,60 @@ export interface FeishuSetupInput {
      * works as-is: it matches the pattern and is unique per agent by construction.
      */
     account?: string;
-    /** Server default: `'open'`. */
+    /**
+     * Server default: `'open'`. WeChat takes only `'open'` or `'disabled'` — `'allowlist'` is
+     * `400 channel.allowlist_unsupported` there, and `'pairing'` is
+     * `400 channel.pairing_unsupported` on every platform.
+     */
     dm_policy?: string;
-    /** Server default: `'open'`. */
+    /** Server default: `'open'`. Ignored by WeChat, which forces `'disabled'`. */
     group_policy?: string;
 }
+/** @deprecated Use {@link ChannelSetupInput}; this is the same shape under the old name. */
+export type FeishuSetupInput = ChannelSetupInput;
 /**
- * A running Feishu QR registration. Render `verification_uri_complete` to the person
- * doing the binding (typically as a QR code), then poll with `pollFeishuSetup` /
- * `waitForFeishuSetup` until it leaves `pending`. The session expires after
- * `expires_in` seconds.
+ * A running QR registration. Show the person doing the binding whichever URI the platform
+ * answered — `verification_uri_complete` for Feishu, `qrcode_url` for WeCom and WeChat, so
+ * `session.verification_uri_complete ?? session.qrcode_url` is the value to render — then poll
+ * with {@link ZooworkClient.pollChannelSetup} / {@link ZooworkClient.waitForChannelSetup} until
+ * it leaves `pending`. The session expires after `expires_in` seconds.
+ *
+ * Two of the three are QR-only: WeCom's `qrcode_url` is a URL you encode yourself, and WeChat's
+ * may be a URL *or* an inline `data:image/…` payload you render directly, so check the prefix
+ * before you feed it to a QR encoder.
  */
-export interface FeishuSetupSession {
+export interface ChannelSetupSession {
     session_id: string;
-    verification_uri_complete: string;
+    /** Feishu only — the URI to encode into a QR code. */
+    verification_uri_complete?: string;
+    /** WeCom and WeChat — a URL to encode, or (WeChat) an inline `data:image/…` image. */
+    qrcode_url?: string;
     expires_in: number;
-    /** Suggested seconds between polls; the server may omit it. */
+    /** Suggested seconds between polls. Feishu sends it; WeCom and WeChat never do. */
     poll_interval?: number | null;
     [k: string]: unknown;
 }
 /**
- * One poll of a Feishu setup session. The gateway's own vocabulary for `status` is
- * `pending | success | expired | denied | error`; treat anything unknown as
- * still-in-flight rather than throwing.
+ * A running Feishu QR registration — {@link ChannelSetupSession} narrowed to the one platform
+ * that always answers `verification_uri_complete`.
  */
-export interface FeishuPollResult {
+export interface FeishuSetupSession extends ChannelSetupSession {
+    verification_uri_complete: string;
+}
+/**
+ * One poll of a setup session. The gateway's own vocabulary for `status` is
+ * `pending | success | expired | denied | error` (`denied` is Feishu-only); treat anything
+ * unknown as still-in-flight rather than throwing.
+ */
+export interface ChannelPollResult {
     status: string;
     channel_configured?: boolean;
     message?: string | null;
     poll_interval?: number | null;
     [k: string]: unknown;
 }
+/** @deprecated Use {@link ChannelPollResult}; this is the same shape under the old name. */
+export type FeishuPollResult = ChannelPollResult;
 export interface AgentRecord {
     agent_id: string;
     computer_id?: string;
@@ -1053,8 +1139,8 @@ export interface ZooworkClient {
     /**
      * Bind a channel from explicit platform config (the non-QR path) — `config` carries the
      * platform's own credential keys. Answers the created channel (HTTP 201). This is the ONLY
-     * path for Slack and WeCom; Feishu also has the QR flow. See {@link ChannelPlatform} for what
-     * binds and what does not.
+     * path for Slack, an alternative to the QR flow for Feishu and WeCom, and refused outright
+     * for WeChat (`400 channel.weixin_setup_required`). See {@link AddChannelPlatform}.
      *
      * **It is idempotent, not an upsert.** Re-posting an identical body for the same
      * `platform` + `account` answers `201` again and replays the binding you already have — it
@@ -1090,52 +1176,70 @@ export interface ZooworkClient {
         account?: string;
     }): Promise<void>;
     /**
-     * Start the Feishu/Lark QR registration. YOU own the UI: render
-     * `verification_uri_complete` (usually as a QR code) and drive the poll loop —
-     * `waitForFeishuSetup` does the loop part for you.
+     * Start a QR registration on one of the three guided platforms. YOU own the UI: render the
+     * URI the session answers (`verification_uri_complete` for Feishu, `qrcode_url` for WeCom and
+     * WeChat) and drive the poll loop — {@link waitForChannelSetup} does the loop part for you.
      *
-     * Observed defaults: `expires_in: 600`, `poll_interval: 5`. `brand` picks the real host —
-     * `'feishu'` answers an `open.feishu.cn` URI, `'lark'` an `open.larksuite.com` one, so the
-     * brand has to match the workspace the person will approve it in.
+     * What each platform reads from `input`, and what it answers, is in
+     * {@link GuidedSetupPlatform}; the short version is that only Feishu takes `brand`, only
+     * Feishu and WeCom take `account`, and only Feishu sends back a `poll_interval`.
      *
-     * Pick `account` before you show the QR. Approving the scan registers a NEW app in that
-     * Feishu workspace, and only then does the binding get written — so a name clash surfaces as
+     * For Feishu, `brand` picks the real host — `'feishu'` answers an `open.feishu.cn` URI,
+     * `'lark'` an `open.larksuite.com` one — so it has to match the workspace the person will
+     * approve it in.
+     *
+     * Pick `account` before you show the QR. On Feishu, approving the scan registers a NEW app in
+     * that workspace, and only then does the binding get written — so a name clash surfaces as
      * `409 channel.conflict` AFTER someone has scanned, with the freshly registered app left
      * behind in their workspace. Retrying under the same name repeats both. See
      * {@link AddChannelInput.account} for how names are scoped.
      */
-    startFeishuSetup(agentId: string, input?: FeishuSetupInput): Promise<FeishuSetupSession>;
+    startChannelSetup(agentId: string, platform: GuidedSetupPlatform, input?: ChannelSetupInput): Promise<ChannelSetupSession>;
     /**
-     * One poll of a setup session. `status: 'pending'` means keep going; a cancelled or expired
-     * session answers `404 channel.feishu_session_not_found` rather than a terminal status, so
-     * a hand-rolled loop must treat that 404 as an end condition, not as a transport error.
+     * One poll of a setup session. `status: 'pending'` means keep going; a cancelled session
+     * answers `404 channel.{platform}_session_not_found` rather than a terminal status, so a
+     * hand-rolled loop must treat that 404 as an end condition, not as a transport error.
      */
-    pollFeishuSetup(agentId: string, sessionId: string): Promise<FeishuPollResult>;
-    /** Abandon a setup session. Afterwards polling it answers `404 channel.feishu_session_not_found`. */
-    cancelFeishuSetup(agentId: string, sessionId: string): Promise<void>;
+    pollChannelSetup(agentId: string, platform: GuidedSetupPlatform, sessionId: string): Promise<ChannelPollResult>;
+    /** Abandon a setup session. Afterwards polling it answers `404 channel.{platform}_session_not_found`. */
+    cancelChannelSetup(agentId: string, platform: GuidedSetupPlatform, sessionId: string): Promise<void>;
     /**
-     * Poll a Feishu setup session until it leaves `pending`, then hand back that terminal poll.
+     * Poll a setup session until it leaves `pending`, then hand back that terminal poll.
      * A status the server reports in the body — `success` / `expired` / `denied` / `error` — is
      * RETURNED, not thrown: "the person rejected it" is an outcome, not an exception.
      *
      * But a session can also stop existing, and then polling answers
-     * `404 channel.feishu_session_not_found`, which surfaces here as a thrown
-     * {@link ZooworkError} carrying that `type`. Confirmed for a cancelled session
-     * (staging 2026-08-25); whether a session that simply runs past `expires_in` reports
-     * `status: 'expired'` in a 200 or disappears into this 404 was NOT observed — handle both.
+     * `404 channel.{platform}_session_not_found`, which surfaces here as a thrown
+     * {@link ZooworkError} carrying that `type`. Confirmed for a cancelled session on all three
+     * platforms (staging 2026-08-28); whether a session that simply runs past `expires_in`
+     * reports `status: 'expired'` in a 200 or disappears into this 404 was NOT observed — handle
+     * both.
      *
-     * Pacing follows the server's `poll_interval` when present (observed default 5s; the local
-     * fallback matches). The default budget is 600s, which is also the observed `expires_in` —
-     * pass the session's own value when you have it. On timeout it throws `status: 408` /
-     * `type: 'timeout'`; on abort, `status: 0` / `type: 'aborted'` — both synthesized locally,
-     * and every in-flight poll is bounded the way {@link waitUntilRunning} bounds its polls.
-     * `onPoll` fires after every poll, terminal one included, for progress UI.
+     * Pacing follows the server's `poll_interval` when present (Feishu sends 5s; WeCom and WeChat
+     * send none and fall back to the same 5s). The default budget is 600s, which matches Feishu's
+     * `expires_in` but is twice WeCom's and WeChat's 300s — pass the session's own value when you
+     * have it. On timeout it throws `status: 408` / `type: 'timeout'`; on abort, `status: 0` /
+     * `type: 'aborted'` — both synthesized locally, and every in-flight poll is bounded the way
+     * {@link waitUntilRunning} bounds its polls. `onPoll` fires after every poll, terminal one
+     * included, for progress UI.
      */
+    waitForChannelSetup(agentId: string, platform: GuidedSetupPlatform, sessionId: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        onPoll?: (poll: ChannelPollResult) => void;
+    }): Promise<ChannelPollResult>;
+    /** Feishu-only spelling of {@link startChannelSetup}, kept for callers written against 0.3.x–0.4.x. */
+    startFeishuSetup(agentId: string, input?: ChannelSetupInput): Promise<FeishuSetupSession>;
+    /** Feishu-only spelling of {@link pollChannelSetup}. */
+    pollFeishuSetup(agentId: string, sessionId: string): Promise<ChannelPollResult>;
+    /** Feishu-only spelling of {@link cancelChannelSetup}. */
+    cancelFeishuSetup(agentId: string, sessionId: string): Promise<void>;
+    /** Feishu-only spelling of {@link waitForChannelSetup}. */
     waitForFeishuSetup(agentId: string, sessionId: string, opts?: {
         timeoutMs?: number;
         signal?: AbortSignal;
-        onPoll?: (poll: FeishuPollResult) => void;
-    }): Promise<FeishuPollResult>;
+        onPoll?: (poll: ChannelPollResult) => void;
+    }): Promise<ChannelPollResult>;
     /**
      * The agent's system-prompt pin and the rendered template in effect. Staging-verified
      * 2026-08-14 — a fresh agent answers a real `declaration` (`{source:'platform',version:1}`),

package/dist/client.js

@@ -39,6 +39,11 @@ function stripTrailingSlashes(url) {
         end--;
     return end === url.length ? url : url.slice(0, end);
 }
+/** Statuses whose failure class tends to pass on its own: timeout, throttle, gateway. */
+const RETRYABLE_STATUSES = new Set([408, 429, 502, 503, 504]);
+/** Bound on `ZooworkError.bodySnippet` — enough to keep a whole error envelope or the
+ * opening of an HTML error page, small enough to log unconditionally. */
+const BODY_SNIPPET_LIMIT = 600;
 export class ZooworkError extends Error {
     status;
     /**
@@ -52,13 +57,87 @@ export class ZooworkError extends Error {
      * you only need the class of failure.
      */
     type;
-    constructor(status, message, type) {
+    /**
+     * `Content-Type` of the error response. The field that tells an edge error page apart from an
+     * API answer: both envelopes above are `application/json`, while a gateway 502/504 arrives as
+     * `text/html` — the edge replaces the origin's body wholesale, so no JSON survives to parse
+     * (verified 2026-08-30 against both deployments;
+     * `notes/probes/system-message-cold-session-probe.mts`).
+     */
+    contentType;
+    /** First {@link BODY_SNIPPET_LIMIT} characters of the raw error body, whatever it was.
+     * Without it a non-JSON failure cannot be reconstructed from `status` alone. */
+    bodySnippet;
+    /**
+     * Cloudflare ray id (`cf-ray` response header), when the response crossed Cloudflare. It
+     * survives even the replaced-body case above — on an HTML 502 it is the only correlation id
+     * left, and the value to quote when reporting a gateway failure.
+     */
+    cfRay;
+    /** Correlation id from the error envelope (`request_id` on either vocabulary), when the
+     * server includes one. Usually absent today. */
+    requestId;
+    /**
+     * Transport-class transient hint: `true` for 408, 429, 502, 503 and 504. It says the failure
+     * CLASS tends to pass, not that a replay is safe — retrying a `postEvents` without an
+     * `idempotency_key` can still deliver twice. Pair it with idempotency keys before looping.
+     */
+    retryable;
+    constructor(status, message, type, extra) {
         super(message);
         this.name = 'ZooworkError';
         this.status = status;
         if (type)
             this.type = type;
+        if (extra?.contentType)
+            this.contentType = extra.contentType;
+        if (extra?.bodySnippet)
+            this.bodySnippet = extra.bodySnippet;
+        if (extra?.cfRay)
+            this.cfRay = extra.cfRay;
+        if (extra?.requestId)
+            this.requestId = extra.requestId;
+        this.retryable = extra?.retryable ?? RETRYABLE_STATUSES.has(status);
+    }
+}
+/** The response facts worth keeping on every transport-level ZooworkError, whatever the body. */
+function responseForensics(res, text) {
+    return {
+        contentType: res.headers.get('content-type') ?? undefined,
+        cfRay: res.headers.get('cf-ray') ?? undefined,
+        bodySnippet: text ? text.slice(0, BODY_SNIPPET_LIMIT) : undefined,
+    };
+}
+/**
+ * Build the ZooworkError for a non-2xx response. Unpacks BOTH envelope vocabularies (see
+ * {@link ZooworkError.type}); when neither matches — typically an edge error page whose body
+ * replaced the origin's JSON — the message names status, content-type and ray id instead of a
+ * bare `HTTP 502`. Those three are what turn an "HTTP 502, type: undefined" report into an
+ * answerable one (2026-08-30). A structured `detail` object is deliberately NOT stringified
+ * into the message (`[object Object]`); it stays readable in `bodySnippet`.
+ */
+function httpError(res, text) {
+    const forensics = responseForensics(res, text);
+    let msg;
+    let type;
+    let requestId;
+    try {
+        const j = JSON.parse(text);
+        const detail = typeof j?.detail === 'string' ? j.detail : undefined;
+        msg = j?.error?.message || j?.message || detail || undefined;
+        type = j?.error?.type ?? j?.code;
+        requestId = j?.error?.request_id ?? j?.request_id;
     }
+    catch {
+        /* non-JSON error body — usually the edge speaking, not the API */
+    }
+    if (!msg) {
+        msg =
+            `HTTP ${res.status}` +
+                (forensics.contentType ? ` (${forensics.contentType})` : '') +
+                (forensics.cfRay ? ` [cf-ray ${forensics.cfRay}]` : '');
+    }
+    return new ZooworkError(res.status, msg, type, { ...forensics, requestId });
 }
 /**
  * Create a client.
@@ -90,36 +169,22 @@ export function createZooworkClient(cfg = {}) {
     }
     const bearer = 'serviceToken' in auth ? auth.serviceToken : auth.apiKey;
     /**
-     * TWO error envelopes, one ZooworkError shape, for every helper below.
-     *
-     * The API does not answer failures the same way everywhere — staging-verified 2026-08-07. Most
-     * families send `{ error: { type, message } }`; the agents family sends `{ code, detail }`.
-     * Reading only the first left every agent 404 with `type: undefined` and the message `HTTP 404`,
-     * so both are unpacked here. The codes stay verbatim (`not_found` vs `service_api.not_found`) —
-     * inventing a shared vocabulary would be this SDK guessing, which is what it exists not to do.
+     * TWO error envelopes, one ZooworkError shape, for every helper below — the unpacking (and
+     * why both vocabularies exist) lives in module-level {@link httpError}. The codes stay
+     * verbatim (`not_found` vs `service_api.not_found`) — inventing a shared vocabulary would be
+     * this SDK guessing, which is what it exists not to do.
      */
     const readResponse = async (res, path) => {
         const text = await res.text();
-        if (!res.ok) {
-            let msg = `HTTP ${res.status}`;
-            let type;
-            try {
-                const j = JSON.parse(text);
-                msg = j?.error?.message || j?.message || j?.detail || msg;
-                type = j?.error?.type ?? j?.code;
-            }
-            catch {
-                /* non-JSON error body → keep clean status */
-            }
-            throw new ZooworkError(res.status, msg, type);
-        }
+        if (!res.ok)
+            throw httpError(res, text);
         if (!text)
             return {};
         try {
             return JSON.parse(text);
         }
         catch {
-            throw new ZooworkError(res.status, `non-JSON response: ${path}`);
+            throw new ZooworkError(res.status, `non-JSON response: ${path}`, undefined, responseForensics(res, text));
         }
     };
     /**
@@ -270,7 +335,7 @@ export function createZooworkClient(cfg = {}) {
             let lastSeen = 'unknown';
             const abortedError = () => new ZooworkError(0, `waitUntilRunning(${agentId}) aborted`, 'aborted');
             const timeoutError = () => new ZooworkError(408, `agent ${agentId} did not reach status.desired_state=running within ${timeoutMs}ms ` +
-                `(last seen: ${lastSeen})`, 'timeout');
+                `(last seen: ${lastSeen})`, 'timeout', { retryable: false });
             for (;;) {
                 if (opts.signal?.aborted)
                     throw abortedError();
@@ -336,20 +401,21 @@ export function createZooworkClient(cfg = {}) {
                 body: JSON.stringify({ account: opts.account ?? 'default' }),
             });
         },
-        startFeishuSetup: (agentId, input = {}) => json(`${agents(agentId)}/channels/feishu/setup`, { method: 'POST', body: JSON.stringify(input) }),
-        pollFeishuSetup: (agentId, sessionId) => json(`${agents(agentId)}/channels/feishu/poll${query({ session_id: sessionId })}`),
-        cancelFeishuSetup: async (agentId, sessionId) => {
-            await json(`${agents(agentId)}/channels/feishu/setup/cancel${query({ session_id: sessionId })}`, {
-                method: 'POST',
-            });
+        startChannelSetup: (agentId, platform, input = {}) => json(`${agents(agentId)}/channels/${encodeURIComponent(platform)}/setup`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        }),
+        pollChannelSetup: (agentId, platform, sessionId) => json(`${agents(agentId)}/channels/${encodeURIComponent(platform)}/poll${query({ session_id: sessionId })}`),
+        cancelChannelSetup: async (agentId, platform, sessionId) => {
+            await json(`${agents(agentId)}/channels/${encodeURIComponent(platform)}/setup/cancel${query({ session_id: sessionId })}`, { method: 'POST' });
         },
-        waitForFeishuSetup: async (agentId, sessionId, opts = {}) => {
+        waitForChannelSetup: async (agentId, platform, sessionId, opts = {}) => {
             const timeoutMs = opts.timeoutMs ?? 600_000;
             const deadline = Date.now() + timeoutMs;
             let lastStatus = 'unknown';
-            const abortedError = () => new ZooworkError(0, `waitForFeishuSetup(${agentId}, ${sessionId}) aborted`, 'aborted');
-            const timeoutError = () => new ZooworkError(408, `Feishu setup session ${sessionId} still '${lastStatus}' after ${timeoutMs}ms — ` +
-                'the QR may simply not have been scanned yet; the session itself expires server-side', 'timeout');
+            const abortedError = () => new ZooworkError(0, `waitForChannelSetup(${agentId}, ${platform}, ${sessionId}) aborted`, 'aborted');
+            const timeoutError = () => new ZooworkError(408, `${platform} setup session ${sessionId} still '${lastStatus}' after ${timeoutMs}ms — ` +
+                'the QR may simply not have been scanned yet; the session itself expires server-side', 'timeout', { retryable: false });
             for (;;) {
                 if (opts.signal?.aborted)
                     throw abortedError();
@@ -364,7 +430,7 @@ export function createZooworkClient(cfg = {}) {
                 const budget = setTimeout(cancelPoll, remaining);
                 let result;
                 try {
-                    result = await json(`${agents(agentId)}/channels/feishu/poll${query({ session_id: sessionId })}`, { signal: poll.signal });
+                    result = await json(`${agents(agentId)}/channels/${encodeURIComponent(platform)}/poll${query({ session_id: sessionId })}`, { signal: poll.signal });
                 }
                 catch (e) {
                     if (poll.signal.aborted)
@@ -378,7 +444,7 @@ export function createZooworkClient(cfg = {}) {
                 opts.onPoll?.(result);
                 lastStatus = result.status ?? 'unknown';
                 // Only a literal 'pending' keeps the loop alive… except that an UNKNOWN status is
-                // treated as still-in-flight too (see FeishuPollResult): a new intermediate state on
+                // treated as still-in-flight too (see ChannelPollResult): a new intermediate state on
                 // the server should stretch the wait, not end it with a fake terminal result.
                 const terminal = ['success', 'expired', 'denied', 'error'].includes(lastStatus);
                 if (terminal)
@@ -391,6 +457,12 @@ export function createZooworkClient(cfg = {}) {
                 await sleep(intervalMs, opts.signal);
             }
         },
+        // The Feishu-only spellings, kept for callers written against 0.3.x–0.4.x. `startFeishuSetup`
+        // narrows the return type only — Feishu always answers `verification_uri_complete`.
+        startFeishuSetup: (agentId, input = {}) => client.startChannelSetup(agentId, 'feishu', input),
+        pollFeishuSetup: (agentId, sessionId) => client.pollChannelSetup(agentId, 'feishu', sessionId),
+        cancelFeishuSetup: (agentId, sessionId) => client.cancelChannelSetup(agentId, 'feishu', sessionId),
+        waitForFeishuSetup: (agentId, sessionId, opts = {}) => client.waitForChannelSetup(agentId, 'feishu', sessionId, opts),
         uploadSkill: (zip, opts) => {
             const form = skillForm(zip, opts);
             form.append('scope', opts.scope);
@@ -510,7 +582,7 @@ export function createZooworkClient(cfg = {}) {
                     ...(opts.signal ? { signal: opts.signal } : {}),
                 });
                 if (!res.ok)
-                    throw new ZooworkError(res.status, `events stream HTTP ${res.status}`);
+                    throw httpError(res, await res.text().catch(() => ''));
                 if (!res.body)
                     return;
                 for await (const msg of parseSSE(res.body)) {

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { createZooworkClient, DEFAULT_BASE_URL, ZooworkError, type ZooworkClient, type ZooworkConfig, type ZooworkAuth, type Ownership, type ModelInfo, type AgentResource, type AgentRecord, type AgentStatus, type AgentSkill, type AgentChannel, type ChannelPlatform, type AddChannelInput, type UpdateChannelInput, type FeishuSetupInput, type FeishuSetupSession, type FeishuPollResult, type McpServerDeclaration, type SkillRecord, type SessionRecord, type SessionHistoryEntry, type SessionEvent, type SessionEventPage, type OutboundEvent, type PostEventReceipt, type ApprovalDecision, type ApprovalRecord, type ArtifactPage, type ArtifactRecord, type ArtifactStatus, type OutcomeConfig, type OutcomeEvaluator, type SystemPromptDeclaration, type SystemPromptInfo, type SystemPromptPreview, type SystemPromptPreviewInput, type SystemPromptUpgrade, type ScheduleSpec, type SchedulePayload, type ScheduleInput, type ScheduleUpdate, type ScheduleRecord, type ScheduleRun, type WakeResult, type ExecResult, type EnvironmentConfig, type EnvironmentResource, type EnvironmentRecord, type EnvironmentVersionRecord, } from './client.js';
+export { createZooworkClient, DEFAULT_BASE_URL, ZooworkError, type ZooworkClient, type ZooworkConfig, type ZooworkAuth, type Ownership, type ModelInfo, type AgentResource, type AgentRecord, type AgentStatus, type AgentSkill, type AgentChannel, type ChannelPlatform, type AddChannelPlatform, type GuidedSetupPlatform, type AddChannelInput, type UpdateChannelInput, type ChannelSetupInput, type ChannelSetupSession, type ChannelPollResult, type FeishuSetupInput, type FeishuSetupSession, type FeishuPollResult, type McpServerDeclaration, type SkillRecord, type SessionRecord, type SessionHistoryEntry, type SessionEvent, type SessionEventPage, type OutboundEvent, type PostEventReceipt, type ApprovalDecision, type ApprovalRecord, type ArtifactPage, type ArtifactRecord, type ArtifactStatus, type OutcomeConfig, type OutcomeEvaluator, type SystemPromptDeclaration, type SystemPromptInfo, type SystemPromptPreview, type SystemPromptPreviewInput, type SystemPromptUpgrade, type ScheduleSpec, type SchedulePayload, type ScheduleInput, type ScheduleUpdate, type ScheduleRecord, type ScheduleRun, type WakeResult, type ExecResult, type EnvironmentConfig, type EnvironmentResource, type EnvironmentRecord, type EnvironmentVersionRecord, } from './client.js';
 export { SESSION_EVENT_TYPES, type SessionEventType, PUBLIC_INPUT_EVENT_TYPES, type PublicInputEventType, normalizeEvent, isRunFinished, runOutcome, messageText, assistantText, thinkingText, toolCall, type ToolCall, } from './events.js';
 export { parseSSE, type SSEMessage } from './sse.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoowork-ai/sdk",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "TypeScript SDK for the ZooWork Managed Agents API (Developer Preview)",
   "keywords": [
     "zoowork",