@zoowork-ai/sdk 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 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.7.0 — 2026-09-14
+
+### Added
+
+- **Application-executed custom tools.** Agent resources can declare `custom_tools`; event
+  helpers expose requested calls; and the client can list pending calls, resolve a call, or
+  post typed `user.custom_tool_result` content.
+- **Filtered cursor session listing.** `listSessionPage()` adds the channel, surface,
+  runtime-mode and archive-filtered cursor lane without changing the existing numeric-page
+  behavior of `listSessions()`. Session archive and delete operations are also exposed.
+
+### Changed
+
+- **MCP configuration now covers runtime context and permissions.** Types include metadata
+  context, a server permission default, exact per-tool overrides, and trailing-prefix tool
+  policy selectors.
+- **Channel contracts include direct DingTalk configuration and Feishu document capability
+  state.** Callers can inspect provider, sync, missing-scope and approval-state details from
+  returned capabilities.
+
+## 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

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,22 +57,65 @@ 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
 
 `run.finished` ends a turn; assistant text arrives on `agent.assistant`.
 
 ```ts
-import { assistantText, isRunFinished, runOutcome, toolCall } from '@zoowork-ai/sdk'
+import { assistantText, customToolUse, isRunFinished, runOutcome, toolCall } from '@zoowork-ai/sdk'
 
 for await (const ev of zc.streamEvents(agent.agent_id, session.session_id)) {
   process.stdout.write(assistantText(ev)) // '' for every non-assistant event
@@ -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
@@ -136,13 +201,37 @@ const { exit_code, stdout } = await zc.exec(agent.agent_id, ['bash', '-lc', 'pwd
 
 ## Sessions, approvals, environments
 
-`listSessions`, `archiveSession` and `deleteSession` round out the session surface. There is no
+`listSessions` keeps the legacy numeric-page contract. Use `listSessionPage` for the filtered
+cursor lane: it starts with `sls1:0`, accepts channel/surface/runtime/archive filters, and returns
+`next_cursor` plus a `list_cursor` on each row. Cursors are opaque and bound to the same filters.
+`archiveSession` and `deleteSession` round out the session surface. There is no
 `patchSession`: the gateway does not proxy `PATCH` at all (405), so session `metadata` is fixed at
 creation time.
 
+An application-executed tool is declared in `resource.custom_tools`. When
+`customToolUse(ev)?.phase === 'requested'`, execute the named operation and call
+`resolveCustomToolCall`; `listCustomToolCalls` recovers pending work after a restart. You may also
+post a typed `user.custom_tool_result` event to the owning session. The run reports
+`awaiting_approval` while paused, so use `pending_custom_tool_calls` to distinguish this wait from
+a normal approval. These contracts are source-reviewed and need deployment verification.
+
+```ts
+const call = customToolUse(ev)
+if (call?.phase === 'requested') {
+  await zc.resolveCustomToolCall(agentId, call.callId, {
+    content: [{ type: 'json', value: { price: 42 } }],
+    resolvedBy: 'pricing-service',
+  })
+}
+```
+
 `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 +240,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 +290,41 @@ 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.
+
+Publishing runs through [`.github/workflows/release.yml`](.github/workflows/release.yml). Configure
+the npm package's Trusted Publisher once with organization `SerendipityOneInc`, repository
+`zoowork-sdk-typescript`, workflow `release.yml`, and direct publish permission. No npm token or
+repeated `npm login` is needed after that.
+
+For each release, merge the intended version and changelog, then publish a GitHub Release whose
+tag is exactly `v<package version>` — for example, `v0.7.0`. The workflow verifies that match,
+runs the offline test and build gates, and publishes the public package with npm OIDC. A mismatched
+tag fails before publication, and an existing npm version cannot be overwritten.
+
+The release workflow does not run live E2E or read a staging key. Run `pnpm test:e2e` separately
+before creating the GitHub Release when live verification is required. Use
+`npm publish --dry-run` locally 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;
     /**
@@ -100,6 +123,18 @@ export interface ModelInfo {
     api?: string;
     [k: string]: unknown;
 }
+/** Approval behavior for one MCP server or one of its tools. */
+export type McpToolPermission = 'always_ask' | 'always_allow';
+/** Opt-in runtime coordinates sent only while a tool is executing, never during catalog discovery. */
+export interface McpContextConfig {
+    /** Add the coordinates under `params._meta['ai.zooclaw/context']` on `tools/call`. */
+    meta?: boolean;
+    /** Add the coordinates as `x-zooclaw-*` headers on the tool call's HTTP requests. */
+    headers?: boolean;
+}
+export interface McpToolPermissionOverride {
+    permission: McpToolPermission;
+}
 /**
  * One remote MCP server, declared as `resource.mcp[]` on create or update.
  *
@@ -114,9 +149,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,8 +167,42 @@ 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';
+    /**
+     * Opt in to runtime coordinates for this server. Both switches default to false. The context
+     * can include agent/session/computer ids and, when available, run/turn/config/actor fields.
+     * Catalog discovery never receives it. Header delivery may be unavailable through proxies;
+     * `_meta` is the portable option.
+     */
+    context?: McpContextConfig;
+    /** Default approval behavior for every tool on this server. Omit for the existing default-allow behavior. */
+    permission?: McpToolPermission;
+    /**
+     * Per-tool approval overrides keyed by the server's original tool name, not its
+     * `mcp__<server>__<tool>` name. Keys are exact and cannot contain `*`; at most 64 entries.
+     */
+    tools?: Record<string, McpToolPermissionOverride>;
     [k: string]: unknown;
 }
+/** One application-executed tool declared under {@link AgentResource.custom_tools}. */
+export interface CustomToolDeclaration {
+    /** Unique within the Agent; 1–64 ASCII letters, numbers, `_` or `-`. Reserved runtime names are rejected. */
+    name: string;
+    /** Non-empty tool description, at most 4 KiB UTF-8. */
+    description: string;
+    /** JSON Schema for the input. Its top-level `type` must be `object`; at most 16 KiB serialized. */
+    input_schema: {
+        type: 'object';
+        [k: string]: unknown;
+    };
+    /** Result wait budget in milliseconds. Defaults to 600,000; maximum 86,400,000. */
+    timeoutMs?: number;
+}
 /**
  * The system-prompt pin (`resource.system_prompt`).
  *
@@ -197,7 +269,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[];
@@ -215,9 +292,21 @@ export interface AgentResource {
         version?: number | 'latest';
     }[];
     labels?: Record<string, string>;
+    /**
+     * Tool-surface and approval policy. Name selectors in `allow`, `deny`, `rules[].match.tool`,
+     * `afterRules[].match.tool`, and MCP names in `deferred.pinned` accept an exact name, `*`, or
+     * one trailing `prefix*`. Other wildcard forms match nothing. `alsoAllow` and
+     * `permissions` keys remain exact. Kept open for forward-compatible policy fields.
+     */
     tool_policy?: Record<string, unknown>;
     /** Remote MCP servers. Only unauthenticated ones work today — see {@link McpServerDeclaration}. */
     mcp?: McpServerDeclaration[];
+    /**
+     * Tools executed by your application. At most 32. A model call emits
+     * `agent.custom_tool_use`; return the result with `resolveCustomToolCall` or a
+     * `user.custom_tool_result` event. Source-reviewed; deployment availability is unverified.
+     */
+    custom_tools?: CustomToolDeclaration[];
     /**
      * System-prompt pin. Omitted on create means "the platform version active right now", pinned
      * from then on. REPLACE-ON-WRITE on PUT, like `tool_policy` — see {@link SystemPromptDeclaration}.
@@ -235,15 +324,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;
@@ -272,6 +364,27 @@ export interface AgentSkill {
     }[];
     [k: string]: unknown;
 }
+/** Source-reviewed asynchronous capability-configuration state for one channel feature. */
+export interface AgentChannelCapabilitySync {
+    state: 'pending' | 'applied' | 'retry' | 'error';
+    [k: string]: unknown;
+}
+export interface FeishuChannelProviderStatus {
+    state: 'ready' | 'degraded';
+    missing_scopes: string[];
+    approval_state?: 'pending_admin' | null;
+    [k: string]: unknown;
+}
+export interface FeishuDocumentsCapability {
+    permission_admin_enabled: boolean;
+    sync: AgentChannelCapabilitySync;
+    provider: FeishuChannelProviderStatus;
+    [k: string]: unknown;
+}
+export interface AgentChannelCapabilities {
+    feishu_documents?: FeishuDocumentsCapability | null;
+    [k: string]: unknown;
+}
 /**
  * One platform account bound to an agent, as the channel service reports it.
  * `dm_policy` / `group_policy` are the reachability policies (`'open'` is the
@@ -288,10 +401,13 @@ export interface AgentChannel {
     health?: string;
     status?: string;
     status_code?: string | null;
+    /** Source-reviewed capability state. Omitted when the platform reports none. */
+    capabilities?: AgentChannelCapabilities | null;
     [k: string]: unknown;
 }
 /**
- * The chat platforms you can bind, staging-verified 2026-08-28.
+ * The chat platforms you can bind. Feishu, Slack, WeCom and WeChat were staging-verified
+ * 2026-08-28. Direct DingTalk support is source-reviewed, not deployment-verified here.
  *
  * 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
@@ -300,15 +416,15 @@ export interface AgentChannel {
  *
  * 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`.
+ * is its ONLY path. DingTalk uses `'dingtalk-connector'` and currently has a direct config path
+ * only on the public API; its product QR flow is not exposed here. See {@link AddChannelPlatform}.
  */
-export type ChannelPlatform = 'feishu' | 'slack' | 'wecom' | 'weixin';
+export type ChannelPlatform = 'feishu' | 'slack' | 'wecom' | 'weixin' | 'dingtalk-connector';
 /**
  * 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';
+export type AddChannelPlatform = 'feishu' | 'slack' | 'wecom' | 'dingtalk-connector';
 /**
  * The platforms with a server-driven QR flow: {@link ZooworkClient.startChannelSetup} →
  * render the URI → poll. Slack is absent by design, not by omission.
@@ -357,11 +473,11 @@ export interface AddChannelInput {
      */
     account?: string;
     display_name?: string;
-    /** Server default: `'open'`. `'pairing'` is rejected with `400 channel.pairing_unsupported`. */
+    /** Server default: `'open'`. DingTalk accepts only `'open'`; `'pairing'` is rejected everywhere. */
     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
@@ -371,8 +487,11 @@ export interface AddChannelInput {
      *   needs the app-level token as well as the bot token)
      * - `wecom` — `{ botId, secret }`, both required
      * - `feishu` — `{ appId, appSecret, domain }`, only when skipping the QR flow
+     * - `dingtalk-connector` — `{ clientId, clientSecret }`; no public guided QR route
      */
     config?: Record<string, unknown>;
+    /** Feishu only. Enable document-permission administration; defaults to false. */
+    permission_admin_enabled?: boolean;
 }
 export interface UpdateChannelInput {
     /** Which binding to touch — see {@link AddChannelInput.account}. Server default: `'default'`. */
@@ -380,6 +499,8 @@ export interface UpdateChannelInput {
     dm_policy?: string;
     group_policy?: string;
     enabled?: boolean;
+    /** Feishu only. Other platforms reject this field when it is present. */
+    permission_admin_enabled?: boolean;
 }
 /**
  * Body for {@link ZooworkClient.startChannelSetup}. Every field is optional, and each platform
@@ -422,6 +543,8 @@ export interface ChannelSetupInput {
     dm_policy?: string;
     /** Server default: `'open'`. Ignored by WeChat, which forces `'disabled'`. */
     group_policy?: string;
+    /** Feishu only. Enable document-permission administration; defaults to false. */
+    permission_admin_enabled?: boolean;
 }
 /** @deprecated Use {@link ChannelSetupInput}; this is the same shape under the old name. */
 export type FeishuSetupInput = ChannelSetupInput;
@@ -548,6 +671,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 })`.
  *
@@ -571,7 +704,11 @@ export interface SessionRecord {
      * `getSession` and `listSessions` carry the latest run state (`running`, `succeeded`, …) here.
      * The `createSession` receipt does not include this field.
      */
-    run_status?: string;
+    run_status?: string | null;
+    /** Pending approval count on getSession; not included in every session projection. */
+    pending_approvals?: number;
+    /** Pending application-executed custom-tool count on getSession. */
+    pending_custom_tool_calls?: 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}
@@ -580,17 +717,84 @@ export interface SessionRecord {
     status?: string | null;
     metadata?: Record<string, unknown>;
     archived?: boolean;
+    runtime_mode?: 'active' | 'preview' | 'authoring' | 'evaluation' | string;
+    config_version?: number;
     updated_at?: string;
+    /** Activity sort key used by filtered cursor listing. */
+    last_activity_at?: string;
+    /** Opaque per-row resume cursor returned only by {@link ZooworkClient.listSessionPage}. */
+    list_cursor?: string;
     /** Present only when the read asked for `history: true`; the most recent `limit` rows, in order. */
     history?: SessionHistoryEntry[];
     [k: string]: unknown;
 }
-/** Write-side events: user.message / user.interrupt / user.tool_confirmation / system.message */
+/** Write-side events, including `user.custom_tool_result`; unsupported types are rejected by the API. */
 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;
 }
+export type CustomToolResultImageMimeType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+/** One content block returned by an application-executed custom tool. */
+export type CustomToolResultContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'json';
+    value: unknown;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: CustomToolResultImageMimeType;
+        data: string;
+    };
+} | {
+    type: 'image';
+    data: string;
+    mime_type: CustomToolResultImageMimeType;
+};
+/** Write-side result event for {@link ZooworkClient.postEvents}. */
+export type CustomToolResultEvent = OutboundEvent & {
+    type: 'user.custom_tool_result';
+    content: CustomToolResultContent[];
+    is_error?: boolean;
+    idempotency_key?: string;
+} & ({
+    custom_tool_use_id: string;
+    call_id?: never;
+} | {
+    call_id: string;
+    custom_tool_use_id?: never;
+});
+/** Options for the filtered cursor lane. Filters are part of the cursor scope. */
+export interface SessionListPageOptions {
+    /** Opaque cursor returned by this same filter scope. Omit to start at `sls1:0`. */
+    cursor?: string;
+    /** 1–100; server default 50. */
+    limit?: number;
+    excludeChannels?: string[];
+    includeSurfaces?: string[];
+    runtimeModes?: Array<'active' | 'preview' | 'authoring' | 'evaluation'>;
+    includeArchived?: boolean;
+}
+/** One filtered session page. `next_cursor` is null at the end. */
+export interface SessionListPage {
+    sessions: SessionRecord[];
+    next_cursor: string | null;
+}
 /** One `postEvents` receipt. An accepted event carries the full event object's fields too. */
 export interface PostEventReceipt {
     id?: string | null;
@@ -605,11 +809,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.
@@ -621,7 +824,8 @@ export type ScheduleSpec = {
     [k: string]: unknown;
 } | {
     kind: 'every';
-    every: string | number;
+    everyMs: number;
+    anchorMs?: number;
     tz?: string;
     [k: string]: unknown;
 } | {
@@ -782,13 +986,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;
@@ -809,18 +1016,46 @@ 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;
 }
+export type CustomToolCallStatus = 'pending' | 'completed' | 'timeout' | 'cancelled' | string;
+/** One application-executed custom-tool call. Unknown response fields are preserved. */
+export interface CustomToolCallRecord {
+    call_id: string;
+    session_id: string;
+    tool_call_id: string;
+    name: string;
+    input: Record<string, unknown>;
+    status: CustomToolCallStatus;
+    requested_at: string;
+    timeout_at?: string;
+    resolved_by?: string;
+    resolved_at?: string;
+    is_error?: boolean;
+    /** Resolve receipt: true when a pending call was signaled, false when it was already terminal. */
+    signaled?: boolean;
+    [k: string]: unknown;
+}
 /** Artifact lifecycle. Only a `ready` row carries a resolvable `url`. */
 export type ArtifactStatus = 'pending' | 'ready' | 'failed' | 'deleted' | string;
 /**
@@ -993,10 +1228,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
@@ -1005,8 +1241,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;
@@ -1064,11 +1300,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>;
@@ -1081,13 +1318,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[];
     }>;
@@ -1286,10 +1527,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';
@@ -1300,7 +1542,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`.
@@ -1309,7 +1553,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
@@ -1330,10 +1574,15 @@ export interface ZooworkClient {
         history?: boolean;
         limit?: number;
     }): Promise<SessionRecord>;
-    /** Newest first by `updated_at`, 50 per page, `page` is 1-based. Single page per call — there is no cursor. */
+    /** Legacy newest-first numeric page lane: 50 per page, `page` is 1-based. */
     listSessions(agentId: string, opts?: {
         page?: number;
     }): Promise<SessionRecord[]>;
+    /**
+     * Filtered cursor lane. It is separate from {@link listSessions} so existing numeric-page
+     * callers keep their contract. Cursors are opaque and valid only with the same filters.
+     */
+    listSessionPage(agentId: string, opts?: SessionListPageOptions): Promise<SessionListPage>;
     /**
      * Stamp `archived_at`. Afterwards writes are `409 session_archived` while reads keep working.
      * Interrupt an in-flight run first, or the archive races it.
@@ -1404,16 +1653,28 @@ export interface ZooworkClient {
         cursor?: string;
         signal?: AbortSignal;
     }): AsyncGenerator<SessionEvent>;
+    /** Pending calls only. Any other status is rejected by the API. */
+    listCustomToolCalls(agentId: string, opts?: {
+        status?: 'pending';
+    }): Promise<CustomToolCallRecord[]>;
+    /**
+     * Return one call's result. A pending call answers 202/signaled:true but stays pending until
+     * the paused run consumes it; an already-terminal call answers 200/signaled:false.
+     */
+    resolveCustomToolCall(agentId: string, callId: string, input: {
+        content: CustomToolResultContent[];
+        isError?: boolean;
+        resolvedBy?: string;
+    }): Promise<CustomToolCallRecord>;
     /**
      * Tool calls parked on a human decision. `status` may ONLY be omitted or `'pending'` —
      * 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';
@@ -1422,7 +1683,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
@@ -1540,9 +1801,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;
@@ -1558,15 +1819,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) }),
@@ -498,6 +543,17 @@ export function createZooworkClient(cfg = {}) {
             const data = await json(`${sessions(agentId)}${query({ page: opts.page })}`);
             return data.sessions ?? [];
         },
+        listSessionPage: async (agentId, opts = {}) => {
+            const data = await json(`${sessions(agentId)}${query({
+                cursor: opts.cursor ?? 'sls1:0',
+                limit: opts.limit,
+                exclude_channels: opts.excludeChannels?.join(','),
+                include_surfaces: opts.includeSurfaces?.join(','),
+                runtime_modes: opts.runtimeModes?.join(','),
+                include_archived: opts.includeArchived === undefined ? undefined : String(opts.includeArchived),
+            })}`);
+            return { sessions: data.sessions ?? [], next_cursor: data.next_cursor ?? null };
+        },
         archiveSession: async (agentId, sessionId) => {
             const data = await json(`${sessions(agentId)}/${encodeURIComponent(sessionId)}/archive`, { method: 'POST' });
             return { ...data, archived: data.archived ?? false };
@@ -606,6 +662,14 @@ export function createZooworkClient(cfg = {}) {
                 throw e;
             }
         },
+        listCustomToolCalls: async (agentId, opts = {}) => {
+            const data = await json(`${agents(agentId)}/custom_tool_calls${query({ status: opts.status })}`);
+            return data.custom_tool_calls ?? [];
+        },
+        resolveCustomToolCall: (agentId, callId, input) => json(`${agents(agentId)}/custom_tool_calls/${encodeURIComponent(callId)}/result`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        }),
         listApprovals: async (agentId, opts = {}) => {
             const data = await json(`${agents(agentId)}/approvals${query({ status: opts.status })}`);
             return data.approvals ?? [];
@@ -700,7 +764,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/events.d.ts

@@ -17,10 +17,10 @@
  * and may add types within a version.
  */
 /** SESSION_EVENT_TYPES, mirrored from the API. */
-export declare const SESSION_EVENT_TYPES: readonly ["run.started", "run.finished", "chat.delta", "chat.final", "chat.aborted", "chat.error", "agent.lifecycle", "agent.assistant", "agent.thinking", "agent.tool", "agent.item", "agent.plan", "agent.approval", "agent.command_output", "agent.patch", "agent.compaction", "agent.error", "attachment.created", "message.outbound"];
+export declare const SESSION_EVENT_TYPES: readonly ["run.started", "run.finished", "chat.delta", "chat.final", "chat.aborted", "chat.error", "agent.lifecycle", "agent.assistant", "agent.thinking", "agent.tool", "agent.item", "agent.plan", "agent.approval", "agent.custom_tool_use", "agent.command_output", "agent.patch", "agent.compaction", "agent.error", "attachment.created", "message.outbound"];
 export type SessionEventType = (typeof SESSION_EVENT_TYPES)[number];
 /** Your own inputs, echoed back in the unified event history. */
-export declare const PUBLIC_INPUT_EVENT_TYPES: readonly ["user.message", "user.interrupt", "user.tool_confirmation", "system.message"];
+export declare const PUBLIC_INPUT_EVENT_TYPES: readonly ["user.message", "user.interrupt", "user.tool_confirmation", "user.custom_tool_result", "system.message"];
 export type PublicInputEventType = (typeof PUBLIC_INPUT_EVENT_TYPES)[number];
 /** A durable session event, normalized across the REST and SSE shapes. */
 export interface SessionEvent {
@@ -74,6 +74,20 @@ export interface ToolCall {
     isError?: boolean;
     resultPreview?: string;
 }
+export interface CustomToolUse {
+    phase: 'requested' | 'resolved';
+    callId: string;
+    toolCallId?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+    timeoutAt?: string;
+    outcome?: 'completed' | 'timeout' | 'cancelled';
+    isError?: boolean;
+    resolvedBy?: string;
+    resolutionChannel?: string;
+}
+/** Application-executed custom-tool activity; undefined for every other event type. */
+export declare function customToolUse(e: SessionEvent): CustomToolUse | undefined;
 /**
  * Tool activity for an `agent.tool` event; undefined for every other type.
  *

package/dist/events.js

@@ -31,6 +31,7 @@ export const SESSION_EVENT_TYPES = [
     'agent.item',
     'agent.plan',
     'agent.approval',
+    'agent.custom_tool_use',
     'agent.command_output',
     'agent.patch',
     'agent.compaction',
@@ -43,6 +44,7 @@ export const PUBLIC_INPUT_EVENT_TYPES = [
     'user.message',
     'user.interrupt',
     'user.tool_confirmation',
+    'user.custom_tool_result',
     'system.message',
 ];
 const isObj = (v) => !!v && typeof v === 'object';
@@ -124,6 +126,25 @@ export function thinkingText(e) {
         return '';
     return typeof e.payload.text === 'string' ? e.payload.text : '';
 }
+/** Application-executed custom-tool activity; undefined for every other event type. */
+export function customToolUse(e) {
+    if (e.eventType !== 'agent.custom_tool_use')
+        return undefined;
+    const p = e.payload;
+    const outcome = p.outcome === 'completed' || p.outcome === 'timeout' || p.outcome === 'cancelled' ? p.outcome : undefined;
+    return {
+        phase: p.phase === 'resolved' ? 'resolved' : 'requested',
+        callId: typeof p.callId === 'string' ? p.callId : '',
+        ...(typeof p.toolCallId === 'string' ? { toolCallId: p.toolCallId } : {}),
+        ...(typeof p.name === 'string' ? { name: p.name } : {}),
+        ...(isObj(p.input) ? { input: p.input } : {}),
+        ...(typeof p.timeoutAt === 'string' ? { timeoutAt: p.timeoutAt } : {}),
+        ...(outcome ? { outcome } : {}),
+        ...(typeof p.isError === 'boolean' ? { isError: p.isError } : {}),
+        ...(typeof p.resolvedBy === 'string' ? { resolvedBy: p.resolvedBy } : {}),
+        ...(typeof p.resolutionChannel === 'string' ? { resolutionChannel: p.resolutionChannel } : {}),
+    };
+}
 /**
  * Tool activity for an `agent.tool` event; undefined for every other type.
  *

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 { SESSION_EVENT_TYPES, type SessionEventType, PUBLIC_INPUT_EVENT_TYPES, type PublicInputEventType, normalizeEvent, isRunFinished, runOutcome, messageText, assistantText, thinkingText, toolCall, type ToolCall, } from './events.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 AgentChannelCapabilitySync, type AgentChannelCapabilities, type FeishuChannelProviderStatus, type FeishuDocumentsCapability, type ChannelPlatform, type AddChannelPlatform, type GuidedSetupPlatform, type AddChannelInput, type UpdateChannelInput, type ChannelSetupInput, type ChannelSetupSession, type ChannelPollResult, type FeishuSetupInput, type FeishuSetupSession, type FeishuPollResult, type McpContextConfig, type McpServerDeclaration, type McpToolPermission, type McpToolPermissionOverride, type CustomToolDeclaration, type CustomToolResultImageMimeType, type CustomToolResultContent, type CustomToolResultEvent, type SkillRecord, type SkillVersionRecord, type SessionRecord, type SessionListPageOptions, type SessionListPage, type SessionHistoryEntry, type SessionEvent, type SessionEventPage, type OutboundEvent, type PostEventReceipt, type ApprovalDecision, type ApprovalRecord, type CustomToolCallStatus, type CustomToolCallRecord, 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, customToolUse, type CustomToolUse, toolCall, type ToolCall, } from './events.js';
 export { parseSSE, type SSEMessage } from './sse.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { createZooworkClient, DEFAULT_BASE_URL, ZooworkError, } from './client.js';
-export { SESSION_EVENT_TYPES, PUBLIC_INPUT_EVENT_TYPES, normalizeEvent, isRunFinished, runOutcome, messageText, assistantText, thinkingText, toolCall, } from './events.js';
+export { SESSION_EVENT_TYPES, PUBLIC_INPUT_EVENT_TYPES, normalizeEvent, isRunFinished, runOutcome, messageText, assistantText, thinkingText, customToolUse, toolCall, } from './events.js';
 export { parseSSE } 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.2",
+  "version": "0.7.0",
   "description": "TypeScript SDK for the ZooWork Managed Agents API (Developer Preview)",
   "keywords": [
     "zoowork",
@@ -44,9 +44,16 @@
     "typecheck": "tsc --noEmit",
     "test": "tsc --noEmit && vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "pnpm run typecheck && pnpm run build"
+    "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",
+    "prepack": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && npm run build"
   },
   "devDependencies": {
+    "@types/node": "^22.20.1",
     "tsx": "^4.23.7",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"