@zoowork-ai/sdk 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 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.10.1 — 2026-10-03
+
+- Correct production availability guidance for Files, Database viewer, Schedules and Agent configuration updates.
+- Clarify approval and blocked tool events, stream cursor recovery, repeated deletion and Usage validation.
+- Link to the public developer documentation.
+- Documentation and comments only; no runtime or public API changes. Existing service limitations remain.
+
 ## 0.10.0 — 2026-10-03
 
 - Add Files, read-only Agent Database, Usage, Run Output, action paging/detail and Agent webhook management helpers.

package/README.md

@@ -1,6 +1,6 @@
 # @zoowork-ai/sdk
 
-TypeScript SDK for the [ZooWork Managed Agents](https://github.com/SerendipityOneInc/zoowork-agents-docs) API. Developer Preview.
+TypeScript SDK for the [ZooWork Managed Agents](https://zoowork.ai/docs/) API. Developer Preview.
 
 Zero runtime dependencies — it uses the platform `fetch`, which you can override for edge runtimes and tests. ESM only, Node 20+.
 
@@ -149,7 +149,7 @@ to use the owner; IM sessions reject it. See the field's SDK comment for input c
 
 ## Agent Skills
 
-New Agents receive global Skills by default. Use `listAgentSkills(agentId)` to inspect attached Skills. At create time, `resource.skills` accepts a catalog name or `skill_id`; `include_global_skills: false` or an explicit empty list opts out of automatic Skills. Root Skill uploads are unavailable to Project keys. Keep source changes in your application or the Agent workspace through the Files API.
+New Agents receive global Skills by default. Use `listAgentSkills(agentId)` to inspect attached Skills. At create time, `resource.skills` accepts a catalog name or `skill_id`; `include_global_skills: false` or an explicit empty list opts out of automatic Skills. Root Skill uploads are unavailable to Project keys. Keep source changes in your application; use persona documents for standing instructions and Session messages for text task data.
 
 ## Schedules, wake and exec
 
@@ -357,7 +357,7 @@ and `listEvents` truncates at 500 events with nothing in the response to say it
 
 ## Documentation
 
-Full guides and the capability matrix: **[zoowork-agents-docs](https://github.com/SerendipityOneInc/zoowork-agents-docs)**.
+Full guides and the capability matrix: **[zoowork-agents-docs](https://zoowork.ai/docs/)**.
 
 Runnable examples in [`examples/`](examples):
 
@@ -408,11 +408,6 @@ MIT
 These helpers require an SDK release that includes them. Check the installed declarations before using an example; use the documented HTTP endpoint if the installed release lacks the method.
 
 ```ts
-const files = await zc.getWorkspaceFile(agentId, '/workspace')
-await zc.writeWorkspaceFile(agentId, '/workspace/input.txt', 'hello')
-const bytes = await zc.getWorkspaceFileContent(agentId, '/workspace/result.bin')
-const database = await zc.getAgentDatabase(agentId) // reading never provisions it
-const rows = await zc.getAgentDatabaseRows(agentId, 'results', { limit: 100, offset: 0 })
 const usage = await zc.getUsage({ range: '7d', view: 'both' })
 const endpoint = await zc.createAgentWebhook(agentId, {
   url: 'https://receiver.example/webhook', event_types: ['run.finished'],
@@ -423,9 +418,10 @@ const output = await zc.getRunOutput(agentId, sessionId, runId)
 const approvals = await zc.listApprovalPage(agentId, { sessionId })
 ```
 
-File reads derive `owner_uid` and `org_id` from the Agent projection. Raw file content is
-`Uint8Array`; text writes are not binary uploads. Database inspection is read-only. Usage stays
-within the current key scope. Page helpers retain `next_cursor` and `has_more`; replay cursors
+Direct workspace Files and the database viewer are not supported production workflows.
+Supply text in Session messages, ask the Agent to create and publish Artifacts, and download
+those through the Artifact API. The Agent can use `agent_db` and return query results in its
+reply. Method presence is not production availability. Usage stays within the current key scope. Page helpers retain `next_cursor` and `has_more`; replay cursors
 verbatim. `getApproval` and `getCustomToolCall` read terminal as well as pending actions.
 
 Agent webhook methods include get/update/delete, `rotateAgentWebhookSecret`, `testAgentWebhook`,
@@ -436,5 +432,30 @@ records to learn the result. SDK writes do not retry automatically.
 `createSession` accepts `runtime_mode: 'active'` to pin the current active configuration at
 creation. Omit it to resolve active configuration on later turns. `idle_compaction` preserves
 false, null and omission. MCP tool overrides accept `requireConfirmation?: boolean`.
-`updateAgent` accepts `expected_config_version`; a stale version returns
-`409 active_config_changed`. Ownership-only changes do not increment the configuration version.
+Production `updateAgent` currently rejects `expected_config_version` with
+`400 invalid_declared_key`. Omit it for ordinary last-write-wins updates; serialize competing
+writes in your application. A GET followed by PUT is not atomic. Ownership-only changes do not
+increment the configuration version. The separate `upgradeSystemPrompt` precondition remains supported.
+
+## Current production behavior
+
+- Manual Schedule execution requires `enabled: true`, which also enables automatic firings.
+  A disabled Schedule can return `triggered: true` and still be skipped. The receipt is not a
+  run result; run rows can lack status/session linkage.
+- Approval waiting is `agent.approval` / `requested`; `resolved` ends the approval wait.
+  `agent.tool` / `blocked` ends a call without execution, with no later `end`. Reasons include
+  policy denial, approval denial/timeout/cancellation, or interruption; inspect the event
+  payload's `deniedReason`.
+- Save each processed stream cursor with its Session ID. Pass it when reading a subsequent
+  turn in that Session. No cursor means replay from the beginning, including old `run.finished`.
+  REST events and post-event receipts do not supply a cursor; the last REST page has a null
+  continuation token. There is no current-tail helper. Without a saved cursor, replay and
+  reconstruct state or deliberately start a new conversation; do not synthesize a cursor from seq.
+- First Agent deletion succeeds with 204; repeated deletion returns 404 through the public API.
+  For cleanup retries, interpret 404 as absence only for a known Agent with unchanged key scope.
+  Other-tenant or inaccessible resources also return 404.
+- Invalid Usage parameters can return either `400 usage.invalid_query` or 422 with no business
+  error type. Correct the parameters rather than retrying unchanged. Match status as well as type.
+
+See the [public guides](https://zoowork.ai/docs/) for supported workflows. These notes do not
+change SDK transport behavior or make unavailable endpoints usable.

package/dist/client.d.ts

@@ -1351,10 +1351,13 @@ export interface ZooworkClient extends DeveloperApi {
     listAgents(opts?: AgentListParams): AgentPagePromise;
     getAgent(agentId: string): Promise<AgentRecord>;
     /** PUT declared sections. Ownership-only changes do not bump config_version.
-     * Supply expected_config_version for an atomic version check; a mismatch returns 409 active_config_changed. */
+     * Production currently rejects expected_config_version with 400 invalid_declared_key.
+     * Omit it for last-write-wins updates and serialize competing writes in the application. */
     updateAgent(agentId: string, sections: Record<string, unknown>): Promise<AgentRecord>;
     /**
      * Soft delete: the agent stops resolving on the API, but this is not a resource purge.
+     * The first public-API deletion returns 204; repeating it returns 404. A 404 can also
+     * hide an inaccessible resource, so cleanup retries must retain the original key scope.
      * On gateway releases that carry the channels surface, a successful delete also
      * best-effort disables the agent's bound channels — a failure there never turns the
      * delete into an error, so a chat binding can in rare cases outlive its agent.

package/dist/events.d.ts

@@ -95,8 +95,9 @@ export declare function customToolUse(e: SessionEvent): CustomToolUse | undefine
  * `phase: 'end'` carries `isError` and `resultPreview`. Pair them by `toolCallId` — they are
  * NOT adjacent in the stream when calls run concurrently.
  *
- * `phase: 'blocked'` is a third state (see the Events reference): the call is waiting on an
- * approval and has NOT run. Treat it as pending, not as an end — the matching `agent.approval`
- * event carries the request, and an `end` still follows once it resolves.
+ * `phase: 'blocked'` ends the call without execution; no `end` follows. Reasons include
+ * policy denial, approval denial/timeout/cancellation, or interruption. Inspect
+ * `e.payload.deniedReason` for the reason. Approval waiting uses `agent.approval` with `phase: 'requested'`,
+ * followed by `phase: 'resolved'`. A resolution is not proof of successful execution.
  */
 export declare function toolCall(e: SessionEvent): ToolCall | undefined;

package/dist/events.js

@@ -152,9 +152,10 @@ export function customToolUse(e) {
  * `phase: 'end'` carries `isError` and `resultPreview`. Pair them by `toolCallId` — they are
  * NOT adjacent in the stream when calls run concurrently.
  *
- * `phase: 'blocked'` is a third state (see the Events reference): the call is waiting on an
- * approval and has NOT run. Treat it as pending, not as an end — the matching `agent.approval`
- * event carries the request, and an `end` still follows once it resolves.
+ * `phase: 'blocked'` ends the call without execution; no `end` follows. Reasons include
+ * policy denial, approval denial/timeout/cancellation, or interruption. Inspect
+ * `e.payload.deniedReason` for the reason. Approval waiting uses `agent.approval` with `phase: 'requested'`,
+ * followed by `phase: 'resolved'`. A resolution is not proof of successful execution.
  */
 export function toolCall(e) {
     if (e.eventType !== 'agent.tool')

package/package.json

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