@zoowork-ai/sdk 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 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.6.0 — 2026-09-11
+
+### Changed
+
+- **Breaking: `listAgents()` now resolves to an `AgentPage`, not an array.** Read `.data`
+  for the current page. The SDK preserves `page`, `page_size`, and `total`, and derives a
+  numeric `next_page` (`null` at the end). Existing one-page callers should replace
+  `const agents = await zc.listAgents(opts)` with `const { data: agents } = await zc.listAgents(opts)`.
+- **Agent lists support automatic and manual pagination.** Use
+  `for await (const agent of zc.listAgents(opts))`, or `page.hasNextPage()` /
+  `page.getNextPage()`. Resolved pages are async iterable and provide `iterPages()`.
+  Later requests preserve the original label filters; early loop exit stops further fetches.
+- Missing, invalid, or non-advancing agent pagination metadata now raises an error instead
+  of hiding a partial result. The API's fixed 100-item numeric pagination is unchanged.
+  Cross-page behavior is verified with synthetic offline HTTP tests; the live release
+  smoke covers one Agent/Session turn and cleanup, not a 101-agent pagination walk.
+
+## 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

package/README.md

@@ -26,9 +26,14 @@ The base URL has a working default, so you do not configure an endpoint. Overrid
 
 ```ts
 // 1. Create an agent. Ownership is derived from your key, so `resource` is all you
-//    send; the gateway also seeds the platform credentials the agent needs to call a model.
+//    send. Select a model returned by this deployment instead of relying on a
+//    remembered id or on a server default that can rotate.
+const models = await zc.listModels()
+const primary = models.find((model) => model.model === 'litellm/gpt-5.6-terra')?.model
+if (!primary) throw new Error('Choose a model returned by listModels()')
+
 const agent = await zc.createAgent({
-  resource: { name: 'research-agent', model: { primary: 'litellm/claude-sonnet-5' } },
+  resource: { name: 'research-agent', model: { primary } },
 })
 
 // 2. Start it. Without this, createSession() returns 409 agent_not_running.
@@ -52,15 +57,58 @@ An explicit option always beats the environment variable.
 
 > **Finding the agent you built in the app.** The first path segment of a ZooWork chat URL
 > (`/chat/<32-hex>/sessions/…`) is a *workspace* id, not an `agt_…`. Resolve it with
-> `zc.listAgents({ labels: { workspace_id: '<32-hex>' } })`; a bare `zc.listAgents()` lists
-> everything your key can see. Scope is `owner_uid AND org_id` — an agent a *colleague*
+> `zc.listAgents({ labels: { workspace_id: '<32-hex>' } })`; use the pagination patterns
+> below to read one page or traverse every match. Scope is `owner_uid AND org_id` — an agent a *colleague*
 > created in your org is fetchable by id but will not appear in your list.
 
 > **Wait on `status.desired_state`, never on `status.actual_state`.**
 > `actual_state` reports chat-channel connectivity. An API-only agent has no channels,
-> so it stays at `activating` forever and `active` is unreachable — a readiness loop
-> that polls it never returns. `desired_state` flips to `running` in well under a second.
-> `await zc.waitUntilRunning(agentId)` is that loop, written correctly.
+> but its projection depends on the channel-status capability: a GET can report `active`
+> with zero channel counts and a `status_message` saying health was not verified when that
+> capability is unsupported, while a transient health lookup failure remains `activating`.
+> List and GET can therefore briefly disagree. None of these values is readiness, and
+> `running` is not an `actual_state` value. Use `await zc.waitUntilRunning(agentId)`; it
+> correctly polls `desired_state`.
+
+## Listing agents and pagination
+
+`listAgents()` returns an awaitable, async-iterable request. Use `for await` to traverse all
+matching agents; the SDK requests each next page only as you consume the results:
+
+```ts
+for await (const agent of zc.listAgents({ labels: { project: 'research' } })) {
+  console.log(agent.agent_id)
+  // break when you have enough; later pages will not be fetched.
+}
+```
+
+For a single page, `await` the request and read `.data`. The page preserves `page`,
+`page_size`, and `total`, and exposes `next_page` (`null` when there are no more results):
+
+```ts
+const page = await zc.listAgents()
+console.log(page.data, page.total, page.next_page)
+
+if (page.hasNextPage()) {
+  const next = await page.getNextPage() // retains the original label filters
+  console.log(next.data)
+}
+```
+
+You can also use `for await (const agent of page)` to iterate from an already-fetched page,
+or `for await (const batch of page.iterPages())` to process one page at a time.
+`getNextPage()` rejects if there is no next page; errors fetching later pages reject iteration.
+
+The API uses **numeric pages starting at 1**, with a fixed page size of 100. The SDK derives
+`next_page` from the returned `page`, `page_size`, and `total`; it is a number, not an opaque
+cursor. To resume explicitly, use `zc.listAgents({ page: nextPage, labels: originalLabels })`.
+There is no configurable `limit`. Pagination is not a snapshot: concurrent additions or
+deletions can shift results between pages.
+
+**Migration from the array return:** replace `const agents = await zc.listAgents(opts)` with
+`const { data: agents } = await zc.listAgents(opts)` to keep reading one page, or switch to
+`for await` to read every match. Missing or invalid pagination metadata now raises an error
+instead of silently returning an empty or apparently complete array.
 
 ## Streaming a turn
 
@@ -85,8 +133,14 @@ for await (const ev of zc.streamEvents(agent.agent_id, session.session_id)) {
 Three things worth knowing before you write that loop:
 
 - **The stream is session-scoped and does not close when a turn ends.** The server closes it after an idle period. Break on `isRunFinished(ev)` yourself, or you block until that timeout.
-- **It resumes.** Every frame carries a durable `seq`. After a dropped connection, restart with `{ after: lastSeq }` and the server replays from there — nothing lost, nothing duplicated.
-- **REST and SSE spell the same event differently** (`event_type` vs `eventType`, and neither has a top-level `type`). The SDK normalizes both into one `SessionEvent`; you only ever read `eventType`.
+- **Save the opaque cursor.** After consuming an event, retain `ev.cursor` and resume with `{ cursor }`. Do not derive it from `seq` or mix it with `after`: `after` selects the deprecated event lane, which omits user-input events. The SDK sends the cursor in the query; do not rely on a raw `Last-Event-ID` header passing through the public gateway.
+- **The default unified REST and SSE wire formats use snake_case.** Older event formats differ; the SDK normalizes both into `SessionEvent`, where you read `eventType`. Keep the cursor unchanged.
+
+For API sessions, `user.message` can carry `actor: { ref: 'customer-42' }`, including in
+`initial_events`. This source-reviewed field selects per-user memory attribution. Your server
+must authenticate the user and authorize the session; `actor.ref` does neither. It does not
+isolate the shared agent's sandbox files or erase a session's previous context. Omit `actor`
+to use the owner; IM sessions reject it. See the field's SDK comment for input constraints.
 
 ## Bring your own skill
 
@@ -106,6 +160,13 @@ and it is the first one nearly everyone gets. `scope` is `org` or `personal`; th
 control what a skill says. `uploadSkillVersion` publishes an update, and agents that installed it
 unpinned follow along without another `putAgentSkill`.
 
+`uploadSkillVersion` returns a `SkillVersionRecord` with `version` and `state`, not the
+`latest_version` and `status` of the `SkillRecord` returned by `uploadSkill`. This return
+contract is source-reviewed, not a new live recording. On initial create, put the description
+in the zip's frontmatter: the gateway drops the `description` option. Version uploads can
+use that override. A successful create retried under the same name can return `409 skill_exists`;
+read back first. Version uploads deduplicate identical content for the same skill, not HTTP keys.
+
 ## Schedules, wake and exec
 
 ```ts
@@ -125,6 +186,10 @@ const { exit_code, stdout } = await zc.exec(agent.agent_id, ['bash', '-lc', 'pwd
   `listScheduleRuns`.
 - **`updateSchedule` must omit `sessionTarget`.** It is immutable, and echoing it back from a
   `getSchedule` result — the obvious thing to do — is a 400. The types refuse it for you.
+- **An interval uses `{ kind: 'every', everyMs: 60_000 }`.** Optional `anchorMs` aligns it.
+  The earlier `every` type was incorrect; migrate explicitly, without guessing string units.
+  This correction and optional `ScheduleRun.session_id` are source-reviewed. Use that session
+  link only when present; it is not a run-success indicator.
 - **`exec` resolves on a failed command.** A non-zero exit is still HTTP 200: check `exit_code`,
   don't wait for a rejection. It runs in `/workspace` and needs an agent-scope sandbox.
 - **A cron job can carry an outcome gate.** `payload.outcome` says what "done" looks like — a
@@ -141,8 +206,12 @@ const { exit_code, stdout } = await zc.exec(agent.agent_id, ['bash', '-lc', 'pwd
 creation time.
 
 `listApprovals` / `resolveApproval` expose the approvals resource — `decision` is one of
-`allow-once`, `allow-always`, `deny`. Note that human-in-the-loop is not usable end to end yet: an
-agent parked on an approval spends its whole turn budget waiting.
+`allow-once`, `allow-always`, `deny`. End-to-end approval and turn-budget behavior need
+separate verification on the deployment you use.
+
+Approval response fields are source-reviewed, not end-to-end verified: read `requested_at`,
+`allowed_decisions` and optional timeout/resolution fields defensively. `signaled: true` means
+the resolution was accepted; a returned `status: 'pending'` is not completed execution.
 
 `listEnvironments`, `getEnvironment`, `createEnvironment`, `createEnvironmentVersion`,
 `getEnvironmentVersion` and `archiveEnvironment` manage prebuilt sandbox images (apt/npm/pip
@@ -151,6 +220,14 @@ start: an agent's Environment **freezes on its first sandbox creation** — afte
 is `409 environment_locked`, and stopping the agent does not clear it — and sandbox networking
 defaults to unrestricted unless the Environment declares `networking: { type: 'limited' }`.
 
+Build polling must have a deadline and handle `partial_ready`: some resource classes can be
+ready while others are building or failed. `getEnvironmentVersion(id, version, { resourceClass:
+'starter' })` selects one class; omitting the option keeps the aggregate read. Re-read the
+aggregate before concluding the build is fully ready. These details are source-reviewed.
+
+Channel callers must not use `allow_from` as an access-control list: the public gateway ignores
+it. Use supported `dm_policy` settings.
+
 ## Artifacts and the system prompt
 
 ```ts
@@ -193,6 +270,40 @@ Runnable examples in [`examples/`](examples):
 - [`live-smoke.ts`](examples/live-smoke.ts) — drive one agent through one turn and verify the REST and SSE reads agree.
 - [`capability-probe.ts`](examples/capability-probe.ts) — create a throwaway agent, walk the whole lifecycle, and print a verdict per capability.
 
+## Testing and publishing (maintainers)
+
+Testing and publishing are independent commands. After cloning this repository on a new
+machine, install its locked development dependencies:
+
+```sh
+pnpm install --frozen-lockfile
+```
+
+Run staging E2E explicitly when you want to verify the SDK (Node 22.20+):
+
+```sh
+pnpm test:e2e
+```
+
+The command prepares an isolated test package, prints individual offline cases and timed live
+steps, and asks for a staging API key with input hidden. Submitting the key authorizes one
+temporary Agent/Session, one potentially billable model turn and cleanup. JSON reports remain
+in its printed private directory. The test never publishes. Normal `pnpm test` is offline
+and needs no key. See [E2E and recovery instructions](e2e/README.md) for scope and options.
+
+To publish the checked-out version, use npm normally:
+
+```sh
+npm login
+npm publish
+```
+
+The `prepack` hook rebuilds `dist` from source; `npm publish` then publishes that package with
+your npm account. It does not run E2E, read a staging key or require an E2E result directory.
+You choose when to test and publish, including on different machines. Check the version and
+changelog before publishing; existing npm versions cannot be overwritten. Use
+`npm publish --dry-run` to inspect the package without uploading it.
+
 ## License
 
 MIT

package/dist/client.d.ts

@@ -42,6 +42,29 @@ export interface ZooworkConfig {
     /** Injected fetch for edge runtimes/tests; defaults to globalThis.fetch. */
     fetch?: (input: string, init?: RequestInit) => Promise<Response>;
 }
+export interface AgentListParams {
+    labels?: Record<string, string>;
+    /** Starting page, numbered from 1. The API fixes page size at 100. */
+    page?: number;
+}
+/** A single page. Iterating this object asynchronously continues through subsequent pages. */
+export interface AgentPage extends AsyncIterable<AgentRecord> {
+    /** Agents in this page only. */
+    readonly data: AgentRecord[];
+    readonly page: number;
+    readonly page_size: number;
+    readonly total: number;
+    /** Next numeric page to pass to listAgents, or null at the end. */
+    readonly next_page: number | null;
+    hasNextPage(): boolean;
+    /** Fetch the next page with the same filters. Rejects when there is no next page. */
+    getNextPage(): Promise<AgentPage>;
+    /** Iterate this and subsequent pages, fetching each only when needed. */
+    iterPages(): AsyncIterableIterator<AgentPage>;
+}
+/** Await one page, or use for-await directly to traverse all remaining agents. */
+export interface AgentPagePromise extends Promise<AgentPage>, AsyncIterable<AgentRecord> {
+}
 export declare class ZooworkError extends Error {
     status: number;
     /**
@@ -114,9 +137,12 @@ export interface ModelInfo {
  *    other way to store it, so an authenticated MCP server cannot be made to work today.
  *    Declare public servers only.
  *
- * Phase 1 is remote HTTP only: no stdio, no OAuth. A server that fails its catalog probe does
- * not fail the run — it pins an empty catalog and emits `agent.error` with
- * `kind: 'mcp_connection_failed'`.
+ * Remote HTTP only; no stdio. Catalog failures emit `agent.error` with
+ * `kind: 'mcp_connection_failed'` or `'mcp_authentication_failed'`, a server name,
+ * an errorMessage and an optional reason. Preserve unknown reason values.
+ * Healthy catalogs remain tied to the configuration. Transient failed catalogs can expire:
+ * a later catalog resolution may probe again, not a periodic retry or recovery guarantee.
+ * These failure/recovery details are source-reviewed, not deployment-verified here.
  */
 export interface McpServerDeclaration {
     /** Server slug. Appears in every tool name as `mcp__<name>__<tool>`. No underscores. */
@@ -129,6 +155,12 @@ export interface McpServerDeclaration {
     credential?: string;
     /** Expose only these tool names from this server. Omit for all of them. */
     toolFilter?: string[];
+    /**
+     * How tools reach the model. `deferred` (the default when omitted) keeps them behind
+     * `tool_search` / `tool_describe` until loaded; `direct` declares them on the first request.
+     * There is no `auto` value.
+     */
+    exposure?: 'deferred' | 'direct';
     [k: string]: unknown;
 }
 /**
@@ -197,7 +229,12 @@ export interface OutcomeConfig {
 }
 export interface AgentResource {
     name: string;
-    /** `max_tokens` caps output tokens per model request. Omit to use the platform default. */
+    /**
+     * Omit this section to pin the platform's current model defaults at create time. Those
+     * defaults can rotate; call `listModels()` and set `primary` explicitly for deterministic
+     * provisioning. `max_tokens` caps output tokens per model request; omit only that field to
+     * use the platform token limit.
+     */
     model?: {
         primary: string;
         input?: string[];
@@ -235,15 +272,18 @@ export interface AgentResource {
     environment_version?: number;
 }
 /**
- * Agent lifecycle state. Two fields, two very different meanings — staging-verified
- * 2026-08-06:
+ * Agent lifecycle state. Two fields, two very different meanings:
  *
  *  - `desired_state` is the one that gates the API. `running` is the precondition for
  *    createSession/postEvents; anything else is `409 agent_not_running`.
- *  - `actual_state` is CHANNEL health (Mattermost/Feishu route connectivity), not API
- *    readiness. An API-only agent has no channels to connect, so it sits at
- *    `activating` forever and `active` is unreachable. Never gate on it, and never
- *    poll for `running` — that is not one of its values.
+ *  - `actual_state` is a best-effort CHANNEL-health projection, not API readiness. When
+ *    route-status is unsupported, GET can report `active` with zero channel counts and a
+ *    `status_message` saying health was not verified; a transient unknown remains
+ *    `activating`. `listAgents` does not make the same foreground health query, so list and
+ *    GET can briefly differ. Never gate on this field, and never poll it for `running` —
+ *    that is not one of its values.
+ *
+ * The channel fallback behavior is source-reviewed, not deployment-verified here.
  */
 export interface AgentStatus {
     desired_state?: 'running' | 'stopped' | 'deleted' | string;
@@ -361,7 +401,7 @@ export interface AddChannelInput {
     dm_policy?: string;
     /** Server default: `'open'`. */
     group_policy?: string;
-    /** Write-once at create; updates cannot edit it. */
+    /** Retained for compatibility; the public gateway ignores this field. It is NOT an access allowlist. Use supported dm_policy settings. */
     allow_from?: string[];
     /**
      * Platform credentials for the direct (non-QR) path. Keys are platform-specific and
@@ -548,6 +588,16 @@ export interface SkillRecord {
     };
     [k: string]: unknown;
 }
+/**
+ * The version row returned by uploadSkillVersion, not a SkillRecord.
+ * Source-reviewed fields; no new live recording is implied. The response stays unmodified.
+ */
+export interface SkillVersionRecord {
+    skill_id: string;
+    version: string | number;
+    state: 'pending' | 'ready' | 'failed' | string;
+    [k: string]: unknown;
+}
 /**
  * One `session_transcripts` row, as projected by `getSession(…, { history: true })`.
  *
@@ -568,12 +618,17 @@ 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 | null;
+    /** Pending approval count on getSession; not included in every session projection. */
+    pending_approvals?: number;
+    /**
+     * `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.
      */
-    run_status?: string;
-    /** Observed `null` on `getSession`. Prefer {@link SessionRecord.run_status} from `listSessions`. */
     status?: string | null;
     metadata?: Record<string, unknown>;
     archived?: boolean;
@@ -586,6 +641,18 @@ export interface SessionRecord {
 export interface OutboundEvent {
     type: string;
     content?: unknown;
+    /**
+     * user.message on an API session only, including createSession.initial_events.
+     * ref is 1–200 ASCII characters from [A-Za-z0-9._:@+-]. Omit actor to use the owner.
+     * Map an authenticated application user to a stable opaque ref on YOUR server.
+     * This selects memory attribution, not authentication, session authorization or file isolation.
+     * IM sessions reject actor; token and other actor keys are rejected with HTTP 400.
+     * Source-reviewed; deployment availability must be verified separately.
+     */
+    actor?: {
+        ref: string;
+        token?: never;
+    };
     [k: string]: unknown;
 }
 /** One `postEvents` receipt. An accepted event carries the full event object's fields too. */
@@ -602,11 +669,10 @@ export interface SessionEventPage {
     nextCursor?: string | null;
 }
 /**
- * When a schedule fires. Three kinds, and only `cron` has its field names pinned by the engine
- * reference (`{"kind":"cron","expr":"0 9 * * *","tz":"Asia/Singapore"}`); `every` and `at` are
- * documented by prose only — "the management plane supports cron/every/at", and an `at`
- * schedule "uses the supplied ISO instant". Their extra fields are therefore left open rather
- * than guessed at, so anything the engine accepts still type-checks.
+ * When a schedule fires: cron expression, everyMs interval in milliseconds (optional
+ * anchorMs), or an ISO instant in at. The everyMs contract is source-reviewed; it was
+ * previously misdeclared as every. Use everyMs explicitly: the SDK does not convert units
+ * or rename the obsolete every field at runtime.
  *
  * Cron is a five-field expression. Macros and a `CRON_TZ=` prefix are rejected; overlap is
  * fixed to SKIP server-side, so a fire that lands on a still-running one is dropped, not queued.
@@ -618,7 +684,8 @@ export type ScheduleSpec = {
     [k: string]: unknown;
 } | {
     kind: 'every';
-    every: string | number;
+    everyMs: number;
+    anchorMs?: number;
     tz?: string;
     [k: string]: unknown;
 } | {
@@ -779,13 +846,16 @@ export interface ScheduleRecord {
  *    This is the only row that carries `status` (e.g. `skipped` for a fire against a disabled
  *    schedule).
  *
- * NEITHER carries `session_id`, which is the field people expect most: you cannot walk from a
- * fire to the session it created. To find that session, list the agent's sessions and match
- * `channel: 'cron'` with the `session_key` prefix `agent:{agent_id}:cron:{schedule_id}:`.
+ * Source-reviewed additions can include session_id when the fire has a known session.
+ * It is optional, not proof of success, and may be absent for command jobs or an unlinked
+ * fire. Older recordings above omit it. Without it, list the agent's sessions and match
+ * channel: 'cron' with the session_key prefix agent:{agent_id}:cron:{schedule_id}:.
  */
 export interface ScheduleRun {
     /** Which projection this row came from. Decides which of the field groups below is populated. */
     source?: 'temporal' | 'run_projection' | string;
+    /** Present only when a session can be associated with this fire. */
+    session_id?: string;
     /** Un-qualified `schedule_id`. */
     schedule_id?: string;
     fired_at?: string;
@@ -806,15 +876,25 @@ export type ApprovalDecision = 'allow-once' | 'allow-always' | 'deny';
 /**
  * A tool call parked on a human decision.
  *
- * Field names are unverified: the only staging observation (2026-08-07) is a 200 with an EMPTY
- * `approvals` array, because producing a real pending approval requires a tool policy that asks.
- * Read defensively.
+ * Fields below are source-reviewed; the existing live recordings have empty lists.
+ * A resolve receipt can have signaled:true while status is still pending: acceptance is not
+ * completion of the tool or run. Verify the resulting state separately.
  */
 export interface ApprovalRecord {
     approval_id?: string;
     session_id?: string;
     tool_name?: string;
     status?: string;
+    arguments_preview?: string;
+    stake?: unknown;
+    requested_at?: string;
+    timeout_at?: string;
+    allowed_decisions?: ApprovalDecision[];
+    resolved_by?: string;
+    resolved_at?: string;
+    signaled?: boolean;
+    decision?: ApprovalDecision;
+    /** Legacy compatibility field; current source projects requested_at instead. */
     created_at?: string;
     [k: string]: unknown;
 }
@@ -990,10 +1070,11 @@ export interface EnvironmentRecord {
     [k: string]: unknown;
 }
 /**
- * One immutable Environment version. Builds walk
- * `queued → submitting → building → verifying → ready`, and any phase can land in `failed`.
- * Poll THIS, not the Environment's top-level row: a `ready` version is the only thing an agent
- * can pin, and it always carries both `e2b_build_id` and a matching `template_ref`.
+ * One immutable Environment version's build state. Builds can be queued, submitting, building,
+ * verifying, partial_ready, ready or failed. partial_ready means some resource classes are
+ * ready; others may still be building or may have failed. It is not by itself a success/failure
+ * verdict for your selected class. Poll with a deadline; optionally read that resourceClass
+ * and re-read the aggregate before drawing a conclusion.
  *
  * THE FIELD IS `status`, NOT `state` — staging-verified 2026-08-07. A poll loop written against
  * `state` compares `undefined` to `'ready'` forever and never terminates, which is precisely the
@@ -1002,8 +1083,8 @@ export interface EnvironmentRecord {
 export interface EnvironmentVersionRecord {
     environment_id?: string;
     version?: number;
-    /** `queued` → `submitting` → `building` → `verifying` → `ready`, or `failed`. */
-    status?: 'queued' | 'submitting' | 'building' | 'verifying' | 'ready' | 'failed' | string;
+    /** Build status; partial_ready may be transient or a partial terminal result. */
+    status?: 'queued' | 'submitting' | 'building' | 'verifying' | 'partial_ready' | 'ready' | 'failed' | string;
     /** The normalized config this version was built from — not the one you posted verbatim. */
     config?: EnvironmentConfig;
     base_environment_id?: string;
@@ -1061,11 +1142,12 @@ export interface ZooworkClient {
      *
      * Note the scope is `owner_uid AND org_id`: an agent a colleague created in your org is
      * fetchable by `getAgent` but will not appear here.
+     *
+     * `await listAgents()` returns one {@link AgentPage}; read `.data` for its agents and
+     * `.next_page` / `.hasNextPage()` for continuation. `for await (const agent of listAgents())`
+     * automatically fetches subsequent pages. Breaking the loop stops further requests.
      */
-    listAgents(opts?: {
-        labels?: Record<string, string>;
-        page?: number;
-    }): Promise<AgentRecord[]>;
+    listAgents(opts?: AgentListParams): AgentPagePromise;
     getAgent(agentId: string): Promise<AgentRecord>;
     /** PUT declared sections; bumps config_version on EVERY call — gate on drift, don't blind-retry. */
     updateAgent(agentId: string, sections: Record<string, unknown>): Promise<AgentRecord>;
@@ -1078,13 +1160,17 @@ export interface ZooworkClient {
     deleteAgent(agentId: string): Promise<void>;
     /**
      * Flip `desired_state` to `running` — the precondition for every session call.
-     * Fast (sub-second on staging). The returned warnings are informational: an
-     * API-only agent reports `channel_routes_reload_failed` on every start/stop
-     * because it has no chat-channel routes to reload. Do not treat it as failure.
+     * A successful response can contain warnings. A non-2xx response still throws ZooworkError;
+     * warnings are not guaranteed on each start/stop and are not a substitute for error handling.
      */
     startAgent(agentId: string): Promise<{
         warnings: string[];
     }>;
+    /**
+     * Request stopped state. Dependency failures can reject after desired_state changes.
+     * Read back and reconcile; desired_state alone does not prove all runtime work is cleaned up.
+     * A successful response's warnings and a rejected HTTP call are different outcomes.
+     */
     stopAgent(agentId: string): Promise<{
         warnings: string[];
     }>;
@@ -1283,10 +1369,11 @@ export interface ZooworkClient {
      * accepted. `SKILL.md` must be non-empty and declare both `name` and `description`.
      * 50 MB expanded, zip only (store/deflate), encrypted zips rejected.
      *
-     * `scope` may only be `org` or `personal`; `global` and `pack` are 403 and are published
-     * through an admin surface the gateway does not proxy. The gateway rewrites ownership to your
-     * key's tenant either way. Staging-verified 2026-08-07 — this is the ONLY path by which an
-     * API-key caller can add a skill the agent will actually load.
+     * scope is org or personal. Other values are rejected by the public gateway with HTTP 400.
+     * Ownership comes from your key. On this CREATE operation the public gateway drops the
+     * description option: put the description in the zip's frontmatter instead.
+     * idempotencyKey is retained as a transport option, not a replay guarantee for Skill uploads.
+     * A retry after a successful create can return 409 skill_exists; read back before retrying.
      */
     uploadSkill(zip: Blob | ArrayBuffer | Uint8Array, opts: {
         scope: 'org' | 'personal';
@@ -1297,7 +1384,9 @@ export interface ZooworkClient {
     /**
      * Publish a new version of an existing skill from a zip. Same zip rules as
      * {@link ZooworkClient.uploadSkill}, plus: the frontmatter `name` must match the target
-     * skill's name. `description` overrides the one in the frontmatter.
+     * skill's name. Unlike root create, description can override the frontmatter here.
+     * Returns a version row (version/state), not a SkillRecord (latest_version/status).
+     * Identical content for the same skill is deduplicated by content, not by Idempotency-Key.
      *
      * Agents that installed the skill unpinned follow the new version on their own — the registry
      * bumps their `config_version`; you do not re-`putAgentSkill`.
@@ -1306,7 +1395,7 @@ export interface ZooworkClient {
         fileName?: string;
         description?: string;
         idempotencyKey?: string;
-    }): Promise<SkillRecord>;
+    }): Promise<SkillVersionRecord>;
     /**
      * The catalog visible to your key: global skills plus your org/personal ones. `q` matches on
      * name; `page` is 1-based with a fixed page size of 100. Only the `org`/`personal` rows are
@@ -1406,11 +1495,10 @@ export interface ZooworkClient {
      * staging-verified 2026-08-07; any other value is rejected, so there is no way to list
      * resolved ones.
      *
-     * Approvals are a REST resource here, NOT the `user.tool_confirmation` event loop; the two
-     * shapes describe the same act and do not line up. Without a Temporal signaler the route
-     * answers `501 not_configured`. We have never produced a real pending approval, so the
-     * round trip is unproven: treat human-in-the-loop as unavailable, and note that a run parked
-     * on an approval burns its whole turn budget waiting.
+     * Approvals are a REST resource here, not an interchangeable user.tool_confirmation
+     * payload. A deployment without approval support can return 501 not_configured.
+     * The response contract is source-reviewed; end-to-end approval and turn-budget behavior
+     * need separate verification on the deployment you use.
      */
     listApprovals(agentId: string, opts?: {
         status?: 'pending';
@@ -1419,7 +1507,7 @@ export interface ZooworkClient {
     resolveApproval(agentId: string, approvalId: string, input: {
         decision: ApprovalDecision;
         resolvedBy?: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<ApprovalRecord>;
     /**
      * Artifacts this agent published, one page per call — but unlike `listEvents`, the page SAYS
      * when it truncated: read `has_more`. `limit` defaults to 50, capped at 100; filter by
@@ -1537,9 +1625,9 @@ export interface ZooworkClient {
      *
      * `resource.config` takes exactly four keys — packages / files / build / networking — and
      * anything else is `400 invalid_environment_config`. Building is asynchronous: poll
-     * `getEnvironmentVersion` until `status === 'ready'` before pinning it on an agent, or the
-     * create answers `409 environment_not_ready`. The field is `status` — there is no `state` on a
-     * version, and a loop written against one never terminates.
+     * getEnvironmentVersion with a deadline before pinning it on an agent. Handle failed and
+     * partial_ready explicitly; selected-class readiness is different from aggregate readiness.
+     * The field is status, not state. A loop without a timeout can otherwise wait forever.
      */
     createEnvironment(input: {
         resource: EnvironmentResource;
@@ -1555,15 +1643,17 @@ export interface ZooworkClient {
      */
     archiveEnvironment(environmentId: string): Promise<EnvironmentRecord>;
     /**
-     * Add an immutable version to an existing Environment. Versions never mutate: a retry after a
-     * failed build retries THAT version and keeps its attempt log.
+     * Add a new immutable configuration version to an existing Environment. This is NOT the
+     * separate operation that retries an existing failed version; the SDK does not wrap retry.
      *
      * The route is reachable, but the request body was not exercised against staging on
      * 2026-08-07 — the SDK sends `{ resource: { config } }`, mirroring create.
      */
     createEnvironmentVersion(environmentId: string, config: EnvironmentConfig, idempotencyKey?: string): Promise<EnvironmentVersionRecord>;
-    /** Poll this — not the Environment's top-level state — to decide whether a version is usable. */
-    getEnvironmentVersion(environmentId: string, version: number): Promise<EnvironmentVersionRecord>;
+    /** Read aggregate build state, or one resource class. Source-reviewed selector; use bounded polling. */
+    getEnvironmentVersion(environmentId: string, version: number, opts?: {
+        resourceClass?: 'starter' | 'pro' | 'ultra';
+    }): Promise<EnvironmentVersionRecord>;
 }
 /**
  * Create a client.

package/dist/client.js

@@ -308,12 +308,57 @@ export function createZooworkClient(cfg = {}) {
                 ...(idempotencyKey ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}),
             });
         },
-        listAgents: async (opts = {}) => {
-            const params = { page: opts.page };
-            for (const [k, v] of Object.entries(opts.labels ?? {}))
-                params[`label.${k}`] = v;
-            const data = await json(`/agents${query(params)}`);
-            return data.agents ?? [];
+        listAgents: (opts = {}) => {
+            // Capture the filters once so caller mutations cannot change the scope mid-walk.
+            const labels = { ...opts.labels };
+            const fetchPage = async (pageNumber) => {
+                if (pageNumber !== undefined && (!Number.isSafeInteger(pageNumber) || pageNumber < 1)) {
+                    throw new RangeError('Agent list page must be a positive safe integer');
+                }
+                const params = { page: pageNumber };
+                for (const [k, v] of Object.entries(labels))
+                    params[`label.${k}`] = v;
+                const body = await json(`/agents${query(params)}`);
+                // Missing metadata must not silently turn a partial result into the last page.
+                // Check advancement too, so a server ignoring page cannot cause an endless walk.
+                if (!body || !Array.isArray(body.agents) || body.page !== (pageNumber ?? 1)
+                    || !Number.isSafeInteger(body.page_size) || body.page_size < 1
+                    || !Number.isSafeInteger(body.total) || body.total < 0) {
+                    throw new Error('Invalid agent list pagination: expected agents, page, page_size, and total for the requested page');
+                }
+                const nextPage = body.page < Math.ceil(body.total / body.page_size) ? body.page + 1 : null;
+                const result = {
+                    data: body.agents,
+                    page: body.page,
+                    page_size: body.page_size,
+                    total: body.total,
+                    next_page: nextPage,
+                    hasNextPage: () => nextPage !== null,
+                    getNextPage: async () => {
+                        if (nextPage === null)
+                            throw new Error('No next page');
+                        return fetchPage(nextPage);
+                    },
+                    async *iterPages() {
+                        let page = result;
+                        while (true) {
+                            yield page;
+                            if (!page.hasNextPage())
+                                return;
+                            page = await page.getNextPage();
+                        }
+                    },
+                    async *[Symbol.asyncIterator]() {
+                        for await (const page of result.iterPages())
+                            yield* page.data;
+                    },
+                };
+                return result;
+            };
+            const request = fetchPage(opts.page);
+            return Object.assign(request, {
+                async *[Symbol.asyncIterator]() { yield* await request; },
+            });
         },
         getAgent: (agentId) => json(agents(agentId)),
         updateAgent: (agentId, sections) => json(agents(agentId), { method: 'PUT', body: JSON.stringify(sections) }),
@@ -700,7 +745,7 @@ export function createZooworkClient(cfg = {}) {
             body: JSON.stringify({ resource: { config } }),
             ...(idempotencyKey ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}),
         }),
-        getEnvironmentVersion: (environmentId, version) => json(`${environments(environmentId)}/versions/${encodeURIComponent(String(version))}`),
+        getEnvironmentVersion: (environmentId, version, opts = {}) => json(`${environments(environmentId)}/versions/${encodeURIComponent(String(version))}${query({ resource_class: opts.resourceClass })}`),
     };
     return client;
 }

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 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 { createZooworkClient, DEFAULT_BASE_URL, ZooworkError, type ZooworkClient, type ZooworkConfig, type ZooworkAuth, type Ownership, type ModelInfo, type AgentResource, type AgentRecord, type AgentListParams, type AgentPage, type AgentPagePromise, 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 SkillVersionRecord, 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/dist/sse.d.ts

@@ -1,15 +1,11 @@
 /**
- * SSE line parser for the `/events/stream` endpoint endpoint.
- *
- * Ported from zoowork-app-kit server/zooclaw/sse.ts — that parser is correct against the
- * live wire and needed no changes. The `id:` field matters: The server frames each durable
- * event as `id: <seq>` + `data: <json>`, so dropping the id line would freeze the resume
- * cursor. Web Streams + TextDecoder only, so this runs in workers and browsers as well as
- * Node.
+ * SSE line parser for the /events/stream endpoint.
+ * Preserve id as an opaque string: unified events use it as a resume cursor, while the
+ * legacy lane can send numeric ids. Web Streams + TextDecoder only.
  */
 export interface SSEMessage {
     event: string;
-    /** The SSE `id:` field — the durable seq for the API event frames. */
+    /** The SSE id field, unchanged. Do not parse an opaque resume cursor as a number. */
     id?: string;
     data: unknown;
 }

package/dist/sse.js

@@ -1,11 +1,7 @@
 /**
- * SSE line parser for the `/events/stream` endpoint endpoint.
- *
- * Ported from zoowork-app-kit server/zooclaw/sse.ts — that parser is correct against the
- * live wire and needed no changes. The `id:` field matters: The server frames each durable
- * event as `id: <seq>` + `data: <json>`, so dropping the id line would freeze the resume
- * cursor. Web Streams + TextDecoder only, so this runs in workers and browsers as well as
- * Node.
+ * SSE line parser for the /events/stream endpoint.
+ * Preserve id as an opaque string: unified events use it as a resume cursor, while the
+ * legacy lane can send numeric ids. Web Streams + TextDecoder only.
  */
 export const isObj = (v) => !!v && typeof v === 'object';
 export async function* parseSSE(body) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoowork-ai/sdk",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "TypeScript SDK for the ZooWork Managed Agents API (Developer Preview)",
   "keywords": [
     "zoowork",
@@ -39,16 +39,22 @@
   "publishConfig": {
     "access": "public"
   },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "tsx": "^4.23.7",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "tsc --noEmit && vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "pnpm run typecheck && pnpm run build"
-  },
-  "devDependencies": {
-    "tsx": "^4.23.7",
-    "typescript": "^5.6.0",
-    "vitest": "^3.0.0"
+    "test:e2e": "node e2e/command.ts",
+    "typecheck:e2e": "tsc -p tsconfig.e2e.json",
+    "test:e2e:offline": "node --import tsx --test --test-reporter=spec e2e/*.test.ts",
+    "e2e:prepare": "node e2e/runner.ts prepare",
+    "e2e:run": "node e2e/runner.ts run",
+    "e2e:verify": "node e2e/runner.ts verify"
   }
-}
+}