@zoowork-ai/sdk 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 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.12.0 — 2026-10-14
+
+- Add the Agent default thinking level (Managed API `model.thinking`, live in production from
+  Engine `v0.2.33-release`). New exported types `ThinkingLevel`
+  (`'off' | 'low' | 'medium' | 'high' | 'max'`), `AgentModelUpdate` and `AgentUpdate`.
+  `AgentResource.model.thinking` accepts a level or `null`. `null` in an update clears it, and
+  `{ model: { thinking: null } } satisfies AgentUpdate` type-checks without `primary`.
+- `ModelInfo.thinking` types the new `GET /v1/models` field `{ default, levels }`, which lists the
+  levels a model honours as named. A level a model does not list resolves to the nearest one.
+- `SchedulePayload.thinking` overrides the Agent's level for an `agentTurn` job. On update,
+  omitting it keeps the stored value and `null` clears it.
+- Additive only. Existing calls and types compile unchanged.
+
 ## 0.11.1 — 2026-10-04
 
 - `uploadFile` no longer runs `chown` on the uploaded file or on directories it creates. The

package/README.md

@@ -51,6 +51,29 @@ const session = await zc.createSession(agent.agent_id, {
 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.
 
+To set a default thinking level, read the levels a model supports from `listModels()` and
+choose one of them in `model.thinking` (`'off' | 'low' | 'medium' | 'high' | 'max'`). Omit it to
+use the platform default; send `thinking: null` in an `updateAgent` call to clear it. A schedule's
+`agentTurn` payload accepts the same `thinking` values; on `updateSchedule`, omitting it keeps the
+stored value and `null` clears it.
+
+```ts
+// `models` and `primary` come from the listModels() example above.
+const info = models.find((m) => m.model === primary)
+const wanted: ThinkingLevel = 'high'
+
+// Set the level only when the model supports it; otherwise leave `thinking` out and the
+// Agent follows the platform default.
+const model: AgentResource['model'] = { primary }
+if (info?.thinking?.levels.includes(wanted)) model.thinking = wanted
+
+const tuned = await zc.createAgent({ resource: { name: 'deep-research-agent', model } })
+
+// Clear it later. `model.thinking` merges, so `primary` is not needed. `satisfies AgentUpdate`
+// makes the compiler reject an unknown level (updateAgent itself accepts any object).
+await zc.updateAgent(tuned.agent_id, { model: { thinking: null } } satisfies AgentUpdate)
+```
+
 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

package/dist/client.d.ts

@@ -118,6 +118,12 @@ export interface Ownership {
     project_id?: string | null;
     visibility?: 'private' | 'project';
 }
+/**
+ * Thinking level, in ascending order of reasoning. A model resolves a level it does not list in
+ * `ModelInfo.thinking.levels` to the nearest listed one (ties go up), so `off` on a model that
+ * cannot stop thinking becomes its lowest level.
+ */
+export type ThinkingLevel = 'off' | 'low' | 'medium' | 'high' | 'max';
 export interface ModelInfo {
     model: string;
     display_name?: string;
@@ -132,6 +138,15 @@ export interface ModelInfo {
     selectable?: boolean;
     retire_not_before?: string | null;
     default_for?: string[];
+    /**
+     * Thinking levels that take effect as named on this model, ascending; any other
+     * {@link ThinkingLevel} resolves to the nearest listed one. `default` is what the platform
+     * applies when an Agent sets none. Optional so older servers that omit it still type-check.
+     */
+    thinking?: {
+        default: ThinkingLevel;
+        levels: ThinkingLevel[];
+    };
     [k: string]: unknown;
 }
 /** Approval behavior for one MCP server or one of its tools. */
@@ -281,6 +296,21 @@ export interface OutcomeConfig {
     /** Defaults to `after_satisfied` at run time: an unsatisfied result stays unpublished. */
     publish?: 'after_satisfied' | 'always' | 'never';
 }
+/**
+ * Partial `model` section for {@link ZooworkClient.updateAgent}. `model.thinking` merges on its
+ * own, so `{ thinking: null }` alone clears the declared level; `primary` is not required.
+ */
+export type AgentModelUpdate = Partial<NonNullable<AgentResource['model']>>;
+/**
+ * Opt-in typing for the `sections` argument of `updateAgent`. `updateAgent` itself still takes
+ * `Record<string, unknown>` so existing callers compile unchanged; write
+ * `const update = { model: { thinking: null } } satisfies AgentUpdate` (or annotate with this
+ * type) to have the compiler check `model` and reject an unknown thinking level.
+ */
+export type AgentUpdate = {
+    model?: AgentModelUpdate;
+    [section: string]: unknown;
+};
 export interface AgentResource {
     name: string;
     /** Named IANA timezone used in prompt context and message timestamps, e.g. `Asia/Shanghai`. */
@@ -290,11 +320,16 @@ export interface AgentResource {
      * 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.
+     *
+     * `thinking` is the Agent's default thinking level. Omit it to use the platform default for
+     * the model; send `null` in an update (PUT) to clear a previously declared value. Check
+     * `ModelInfo.thinking.levels` from `listModels()` for the levels a model accepts.
      */
     model?: {
         primary: string;
         input?: string[];
         max_tokens?: number;
+        thinking?: ThinkingLevel | null;
     };
     persona?: {
         docs: {
@@ -884,6 +919,16 @@ export interface SchedulePayload {
      * 2026-08-14 (201, read back verbatim). See {@link OutcomeConfig}.
      */
     outcome?: OutcomeConfig | null;
+    /**
+     * Thinking level for THIS job's turns, outranking the Agent's `model.thinking`. Only an
+     * `agentTurn` payload honours it. On an update it has three states: omit it (or send an empty or
+     * whitespace-only string) to keep the stored value, send `null` to clear it so the job follows
+     * the Agent again, or send a level to set it. The server trims and lowercases a new value and
+     * normalizes legacy spellings (`xhigh`, `minimal`, `adaptive` become `max`, `low`, `medium`);
+     * a stored value written back unchanged stays as is, so a job stored before this change may
+     * still read back a legacy spelling.
+     */
+    thinking?: ThinkingLevel | null;
     [k: string]: unknown;
 }
 export interface ScheduleInput {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 UploadFileResult, type EnvironmentConfig, type EnvironmentResource, type EnvironmentRecord, type EnvironmentVersionRecord, } from './client.js';
+export { createZooworkClient, DEFAULT_BASE_URL, ZooworkError, type ZooworkClient, type ZooworkConfig, type ZooworkAuth, type Ownership, type ModelInfo, type ThinkingLevel, type AgentResource, type AgentModelUpdate, type AgentUpdate, 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 UploadFileResult, 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';
 export { WEBHOOK_EVENT_TYPES, WEBHOOK_SCHEDULE_CONFIG_EVENT_TYPES, type WebhookEventType, isKnownWebhookEventType, knownWebhookEvent, verifyWebhookSignature, unwrapWebhook, signWebhook, ZooworkWebhookError, type WebhookErrorCode, WEBHOOK_ID_HEADER, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SECRET_ENV, WEBHOOK_TOLERANCE_SECONDS, WEBHOOK_DEFAULT_MAX_BODY_BYTES, type WebhookEvent, type WebhookEventFor, type KnownWebhookEvent, type WebhookEventData, type WebhookEventDataByType, type WebhookEventAttribution, type WebhookScheduleRunRef, type WebhookWaitingOnRef, type WebhookRunEventData, type WebhookRunStartedData, type WebhookRunFinishedData, type WebhookRunYieldedData, type WebhookApprovalEventData, type WebhookApprovalRequestedData, type WebhookApprovalResolvedData, type WebhookCustomToolEventData, type WebhookCustomToolRequestedData, type WebhookCustomToolResolvedData, type WebhookOutcomeEvaluatedData, type WebhookSessionCreatedData, type WebhookSessionArchivedData, type WebhookSessionDeletedData, type WebhookScheduleFireData, type WebhookScheduleDispatchedData, type WebhookScheduleDispatchFailedData, type WebhookScheduleSkippedData, type WebhookScheduleFinishedData, type WebhookScheduleConfigData, type WebhookTestData, type WebhookHeaders, type WebhookHeaderSource, type WebhookSignatureHeaders, type VerifyWebhookInput, type VerifiedWebhook, type SignWebhookInput, } from './webhooks.js';

package/package.json

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