@zoowork-ai/sdk 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 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.8.0 — 2026-09-20
+
+### Added
+
+- Model catalog lifecycle metadata, including `selectable` and replacement hints.
+- Deleted Session tombstones in filtered cursor pages through `includeDeleted`.
+- Agent declaration fields for global-Skill opt-out and named user timezones.
+
+### Changed
+
+- Model-selection examples now reject non-selectable catalog rows; selecting one can return
+  `409 model_not_selectable`.
+
+## 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

package/README.md

@@ -29,8 +29,10 @@ The base URL has a working default, so you do not configure an endpoint. Overrid
 //    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 primary = models.find(
+  (model) => model.selectable !== false && model.model === 'litellm/gpt-5.6-terra',
+)?.model
+if (!primary) throw new Error('Choose a selectable model returned by listModels()')
 
 const agent = await zc.createAgent({
   resource: { name: 'research-agent', model: { primary } },
@@ -45,6 +47,15 @@ const session = await zc.createSession(agent.agent_id, {
 })
 ```
 
+`listModels()` can include a model whose retirement has started. Check `selectable !== false`
+before using a catalog row in a new Agent or config. A non-selectable choice returns
+`409 model_not_selectable`; `expired_fallback_to` names the reviewed replacement when present.
+
+Agent resources also accept `userTimezone`, a named IANA timezone used for prompt and message
+time context, and `include_global_skills: false` to disable automatic global Skills while keeping
+explicitly listed Skills. An explicit `skills: []` also opts out. Schedule timezones are configured
+separately.
+
 ## Configuration
 
 | Option | Environment variable | Default |
@@ -115,7 +126,7 @@ instead of silently returning an empty or apparently complete array.
 `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
@@ -201,10 +212,33 @@ 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.
+Pass `{ includeDeleted: true }` to include deletion tombstones for reconciliation; returned rows
+then carry `deleted` and the page carries `includes_deleted: true`. This flag is part of the cursor
+scope, so do not reuse a cursor created without it.
+`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`. End-to-end approval and turn-budget behavior need
 separate verification on the deployment you use.
@@ -291,18 +325,19 @@ temporary Agent/Session, one potentially billable model turn and cleanup. JSON r
 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:
+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.
 
-```sh
-npm login
-npm publish
-```
+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 `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.
+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
 

package/dist/client.d.ts

@@ -121,8 +121,29 @@ export interface ModelInfo {
     display_name?: string;
     family?: string;
     api?: string;
+    expired_at?: string | null;
+    expired_fallback_to?: string | null;
+    retired_at?: string | null;
+    revision?: number;
+    lifecycle_status?: 'active' | 'scheduled' | 'draining' | 'retired' | string;
+    /** `false` means this catalog row cannot be selected for a new Agent or config. */
+    selectable?: boolean;
+    retire_not_before?: string | null;
+    default_for?: 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.
  *
@@ -161,8 +182,36 @@ export interface McpServerDeclaration {
      * 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`).
  *
@@ -229,6 +278,8 @@ export interface OutcomeConfig {
 }
 export interface AgentResource {
     name: string;
+    /** Named IANA timezone used in prompt context and message timestamps, e.g. `Asia/Shanghai`. */
+    userTimezone?: string;
     /**
      * 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
@@ -251,10 +302,27 @@ export interface AgentResource {
         skill_id: string;
         version?: number | 'latest';
     }[];
+    /**
+     * Defaults to true. False disables automatic global Skills without removing explicitly
+     * listed Skills. An explicit empty `skills` array also opts out.
+     */
+    include_global_skills?: boolean;
     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}.
@@ -312,6 +380,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
@@ -328,10 +417,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
@@ -340,15 +432,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.
@@ -397,7 +489,7 @@ 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;
@@ -411,8 +503,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'`. */
@@ -420,6 +515,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
@@ -462,6 +559,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;
@@ -624,6 +723,8 @@ export interface SessionRecord {
     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}
@@ -632,12 +733,20 @@ export interface SessionRecord {
     status?: string | null;
     metadata?: Record<string, unknown>;
     archived?: boolean;
+    /** Present on filtered pages only when `includeDeleted` was requested. */
+    deleted?: 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;
@@ -655,6 +764,59 @@ export interface OutboundEvent {
     };
     [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;
+    /** Include deleted Session tombstones for history reconciliation. Changes the cursor scope. */
+    includeDeleted?: boolean;
+}
+/** One filtered session page. `next_cursor` is null at the end. */
+export interface SessionListPage {
+    sessions: SessionRecord[];
+    next_cursor: string | null;
+    /** Present and true only when deleted tombstones were requested. */
+    includes_deleted?: true;
+}
 /** One `postEvents` receipt. An accepted event carries the full event object's fields too. */
 export interface PostEventReceipt {
     id?: string | null;
@@ -898,6 +1060,24 @@ export interface ApprovalRecord {
     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;
 /**
@@ -1416,10 +1596,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.
@@ -1490,6 +1675,19 @@ 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

package/dist/client.js

@@ -543,6 +543,22 @@ 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),
+                include_deleted: opts.includeDeleted === undefined ? undefined : String(opts.includeDeleted),
+            })}`);
+            return {
+                sessions: data.sessions ?? [],
+                next_cursor: data.next_cursor ?? null,
+                ...(data.includes_deleted === true ? { includes_deleted: true } : {}),
+            };
+        },
         archiveSession: async (agentId, sessionId) => {
             const data = await json(`${sessions(agentId)}/${encodeURIComponent(sessionId)}/archive`, { method: 'POST' });
             return { ...data, archived: data.archived ?? false };
@@ -651,6 +667,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 ?? [];

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 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 { 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoowork-ai/sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "TypeScript SDK for the ZooWork Managed Agents API (Developer Preview)",
   "keywords": [
     "zoowork",
@@ -39,12 +39,6 @@
   "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",
@@ -55,6 +49,13 @@
     "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"
+    "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"
   }
-}
+}