@zoowork-ai/sdk 0.7.0 → 0.8.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.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

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 |
@@ -204,6 +215,9 @@ const { exit_code, stdout } = await zc.exec(agent.agent_id, ['bash', '-lc', 'pwd
 `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.

package/dist/client.d.ts

@@ -121,6 +121,15 @@ 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. */
@@ -269,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
@@ -291,6 +302,11 @@ 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`,
@@ -717,6 +733,8 @@ 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;
@@ -789,11 +807,15 @@ export interface SessionListPageOptions {
     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 {

package/dist/client.js

@@ -551,8 +551,13 @@ export function createZooworkClient(cfg = {}) {
                 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 };
+            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' });

package/package.json

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