@zoowork-ai/sdk 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 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.2 — 2026-09-04
+
+### Documentation
+
+- **`SessionRecord` now describes the response fields the API actually returns.**
+  `createSession()` returns the legacy `status: "running"` field without `run_status`;
+  later reads expose the latest run state through `run_status`, while `status` is nullable
+  and is not the run outcome. This changes the JSDoc emitted in the published declaration
+  files; runtime code and TypeScript signatures are unchanged.
+
+## 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

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;
@@ -536,12 +568,15 @@ export interface SessionRecord {
     /** `api` for sessions you create, `cron` for ones a schedule fired. */
     channel?: string;
     /**
-     * `listSessions` is the surface that carries the run outcome (`succeeded`, …) — and it spells
-     * it `run_status`, not `status`. Staging-verified 2026-08-07: `getSession` returns a `status`
-     * of `null` for the very same session, so reading `status` off a list row gets you nothing.
+     * `getSession` and `listSessions` carry the latest run state (`running`, `succeeded`, …) here.
+     * The `createSession` receipt does not include this field.
      */
     run_status?: string;
-    /** Observed `null` on `getSession`. Prefer {@link SessionRecord.run_status} from `listSessions`. */
+    /**
+     * `running` on a `createSession` receipt, nullable on `getSession`, and absent from
+     * `listSessions` rows. This is not the run outcome; read {@link SessionRecord.run_status}
+     * from a later read instead.
+     */
     status?: string | null;
     metadata?: Record<string, unknown>;
     archived?: boolean;

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,14 +57,88 @@ 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();
@@ -350,7 +415,7 @@ export function createZooworkClient(cfg = {}) {
             let lastStatus = 'unknown';
             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');
+                '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();
@@ -517,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/package.json

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