@zoowork-ai/sdk 0.10.0 → 0.10.2

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.10.2 — 2026-10-04
+
+- Accept `project` in `uploadSkill` for named Project keys.
+- Clarify Skill registry read/write scopes, version publishing, and Agent bindings for Platform keys.
+- Existing calls remain compatible. Project-scoped uploads require service-side support; this SDK release does not deploy the service.
+
+## 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

@@ -676,7 +676,7 @@ export interface AgentRecord {
  */
 export interface SkillRecord {
     skill_id: string;
-    scope?: 'org' | 'personal' | 'global' | 'pack' | string;
+    scope?: 'project' | 'org' | 'personal' | 'global' | 'pack' | string;
     name?: string;
     description?: string;
     latest_version?: number | string | null;
@@ -694,6 +694,7 @@ export interface SkillRecord {
     ownership?: {
         owner_uid?: string | null;
         org_id?: string | null;
+        project_id?: string | null;
         [k: string]: unknown;
     };
     [k: string]: unknown;
@@ -1351,10 +1352,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.
@@ -1405,9 +1409,10 @@ export interface ZooworkClient extends DeveloperApi {
         verbose?: boolean;
     }): Promise<AgentSkill[]>;
     /**
-     * Attach a skill by id. Only skills the caller's tenant owns are installable
-     * through the `/service/v1` gateway (`org` / `personal` scope); `global`
-     * catalog entries are listable but answer 404 here.
+     * Attach a visible Skill by id. Platform keys can attach global, same-org org,
+     * same-Project project, and eligible owner-personal Skills. Binding a visible Skill
+     * does not grant permission to publish its versions or delete its registry record.
+     * Work service tokens retain their org/personal visibility rules.
      */
     putAgentSkill(agentId: string, skillId: string, opts?: {
         enabled?: boolean;
@@ -1571,14 +1576,18 @@ export interface ZooworkClient extends DeveloperApi {
      * accepted. `SKILL.md` must be non-empty and declare both `name` and `description`.
      * 50 MB expanded, zip only (store/deflate), encrypted zips rejected.
      *
-     * 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
+     * Platform keys on deployments with Project Skill registry support use project scope for a
+     * named Project and org scope for the Default Project. Ownership is derived from the key;
+     * Default Project org Skills are shared across the Organization. Other scopes return
+     * 400 service_api.invalid_body. Work service tokens retain org/personal create scopes.
+     * Older deployments may reject Platform registry requests with 404; SDK support alone
+     * does not prove deployment availability. On CREATE 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';
+        scope: 'project' | 'org' | 'personal';
         fileName?: string;
         description?: string;
         idempotencyKey?: string;
@@ -1589,6 +1598,10 @@ export interface ZooworkClient extends DeveloperApi {
      * 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.
+     * Platform keys can publish only within their write scope: their own named Project's
+     * project Skills, or their Organization's org Skills for a Default Project key. Visible
+     * global/personal Skills and a named Project's visible org Skills remain read-only in the
+     * registry; writes return 404 service_api.not_found. Requires Project registry deployment support.
      *
      * Agents that installed the skill unpinned follow the new version on their own — the registry
      * bumps their `config_version`; you do not re-`putAgentSkill`.
@@ -1599,16 +1612,24 @@ export interface ZooworkClient extends DeveloperApi {
         idempotencyKey?: string;
     }): 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
-     * installable — `global` entries list but answer 404 from `putAgentSkill`.
+     * One page of the visible catalog. With Project registry deployment support, Platform keys
+     * see global Skills, their Organization's org Skills, their named Project's project Skills,
+     * and eligible personal Skills owned by the key's owner. Visibility does not grant registry
+     * write permission. Ownership selectors come from the key. Work service tokens retain their
+     * existing catalog behavior. `q` matches name; `page` is 1-based with a page size of 100.
      */
     listSkills(opts?: {
-        scope?: 'org' | 'personal' | 'global' | string;
+        scope?: 'project' | 'org' | 'personal' | 'global' | string;
         q?: string;
         page?: number;
     }): Promise<SkillRecord[]>;
-    /** 204. No in-use guard for org/personal skills: agents holding it just lose it. */
+    /**
+     * Delete the registry Skill (204), not just one Agent binding. Platform keys require Project
+     * registry deployment support and may delete only their own named Project's project Skills
+     * or, for a Default Project key, their Organization's org Skills. Other IDs, including visible
+     * read-only Skills, return 404 service_api.not_found. Check consumers before deleting a shared
+     * org Skill; use deleteAgentSkill to detach only one Agent.
+     */
     deleteSkill(skillId: string): Promise<void>;
     createSession(agentId: string, input: {
         initial_events?: OutboundEvent[];

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.2",
   "description": "TypeScript SDK for the ZooWork Managed Agents API (Developer Preview)",
   "keywords": [
     "zoowork",