@zoowork-ai/sdk 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.11.0 — 2026-10-04
+
+- Add `uploadFile(agentId, path, content)`, which copies a file into an Agent's sandbox through
+  `exec` and verifies its SHA-256 there. Verified against staging on 2026-10-04 with files up
+  to 3 MiB.
+- Deprecate `getWorkspaceFile`, `writeWorkspaceFile` and `getWorkspaceFileContent`. The hosted
+  service does not enable the workspace Files routes, so these calls fail with HTTP 501 or 502
+  ([ecap #4006](https://github.com/SerendipityOneInc/ecap-workspace/issues/4006)). The methods
+  remain callable.
+
+## 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.

package/README.md

@@ -165,6 +165,20 @@ await zc.wake(agent.agent_id, { text: 'Review the pending deployment.' }) // at
 const { exit_code, stdout } = await zc.exec(agent.agent_id, ['bash', '-lc', 'pwd'])
 ```
 
+## Send a file to an Agent
+
+```ts
+import { readFile } from 'node:fs/promises'
+
+const file = await zc.uploadFile(agent.agent_id, 'input/report.pdf', await readFile('report.pdf'))
+// file.path === '/workspace/input/report.pdf'; tell the Agent to read that path.
+```
+
+`uploadFile` copies bytes or a string into the Agent's sandbox and verifies the SHA-256 there
+before the file appears at its path. A relative path resolves against `/workspace`. It sends the
+content through `exec` about 72 KB per call, so it suits files up to a few megabytes, and it
+needs an agent-scope sandbox.
+
 - **Schedules outlive their agent.** `stopAgent` and `deleteAgent` leave them running; list and
   delete them yourself. Also available: `getSchedule`, `updateSchedule`, `triggerSchedule`,
   `listScheduleRuns`.
@@ -418,9 +432,11 @@ const output = await zc.getRunOutput(agentId, sessionId, runId)
 const approvals = await zc.listApprovalPage(agentId, { sessionId })
 ```
 
-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
+The workspace Files methods (`getWorkspaceFile`, `writeWorkspaceFile`,
+`getWorkspaceFileContent`) are deprecated: the hosted service does not enable those routes.
+Send a file to an Agent with `uploadFile`, and retrieve results by asking the Agent to publish
+Artifacts and downloading those through the Artifact API. The database viewer is not a
+supported production workflow. 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.
 

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;
@@ -1320,6 +1321,15 @@ export interface ExecResult {
     stdout: string;
     stderr: string;
 }
+/** What {@link ZooworkClient.uploadFile} wrote. */
+export interface UploadFileResult {
+    /** Absolute path of the file in the sandbox. */
+    path: string;
+    /** Bytes written. */
+    size: number;
+    /** Lowercase hex SHA-256 of the content, verified inside the sandbox. */
+    sha256: string;
+}
 export interface WakeResult {
     mode: 'now' | 'next-heartbeat' | string;
     /** The reminder was written to the pending queue. */
@@ -1408,9 +1418,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;
@@ -1574,14 +1585,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;
@@ -1592,6 +1607,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`.
@@ -1602,16 +1621,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[];
@@ -1837,6 +1864,23 @@ export interface ZooworkClient extends DeveloperApi {
      * agent's tool path.
      */
     exec(agentId: string, args: string[]): Promise<ExecResult>;
+    /**
+     * Copy a file into the agent's sandbox so the Agent can read it by path.
+     *
+     * `path` is absolute, or relative to `/workspace`; parent directories are created. A string is
+     * written as UTF-8. The content travels through {@link ZooworkClient.exec} in base64 chunks,
+     * lands in a temporary file beside the target, is checked against its SHA-256 inside the
+     * sandbox, and only then moves into place, so a failed upload leaves nothing at `path`. The
+     * file and any directory created for it take the owner of the nearest existing ancestor, so
+     * the Agent's own tools can modify them.
+     *
+     * Each chunk is one `exec` call carrying about 72 KB, so this suits files up to a few
+     * megabytes. It has exec's requirements: an agent-scope sandbox and a rendered config.
+     *
+     * Rejects with `ZooworkError` when a call fails, and with `Error` when a sandbox command exits
+     * non-zero or the checksum does not match.
+     */
+    uploadFile(agentId: string, path: string, content: Blob | ArrayBuffer | Uint8Array | string): Promise<UploadFileResult>;
     /**
      * Environments visible to your org, 1-based `page`. Note that the platform DEFAULT
      * Environment — the one a fresh agent is pinned to — is not in here and is not fetchable: the

package/dist/client.js

@@ -294,6 +294,54 @@ export function createZooworkClient(cfg = {}) {
             throw httpError(res, await res.text());
         return new Uint8Array(await res.arrayBuffer());
     };
+    const exec = (agentId, args) => json(`${agents(agentId)}/exec`, { method: 'POST', body: JSON.stringify({ args }) });
+    /**
+     * Linux caps one argv string at 128 KiB. 72,000 bytes is 96,000 base64 characters, which
+     * leaves room under that cap and is a multiple of 3, so every chunk decodes on its own.
+     */
+    const UPLOAD_CHUNK_BYTES = 72_000;
+    const uploadFile = async (agentId, path, content) => {
+        if (path === '')
+            throw new Error('uploadFile: path is required');
+        const data = typeof content === 'string' ? new TextEncoder().encode(content)
+            : content instanceof Blob ? new Uint8Array(await content.arrayBuffer())
+                : content instanceof ArrayBuffer ? new Uint8Array(content)
+                    : content;
+        const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', data));
+        const sha256 = Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('');
+        // `bash -c SCRIPT NAME ARG…`: values arrive as "$1", "$2", … and are never parsed as shell.
+        const sh = async (script, ...args) => {
+            const res = await exec(agentId, ['bash', '-c', script, 'upload', ...args]);
+            if (res.exit_code !== 0) {
+                throw new Error(`uploadFile: sandbox command exited ${res.exit_code}: ${res.stderr.trim().slice(0, 500)}`);
+            }
+            return res;
+        };
+        const partial = `${path}.upload-${crypto.randomUUID()}`;
+        try {
+            // exec may run as root while the Agent's tools do not. Give the file, and any directory
+            // created for it, the owner of the nearest existing ancestor so the Agent can edit them.
+            await sh('dir=$(dirname "$1"); top=; probe=$dir; '
+                + 'while [ ! -e "$probe" ]; do top=$probe; probe=$(dirname "$probe"); done; '
+                + 'owner=$(stat -c %u:%g "$probe"); mkdir -p "$dir" && : > "$1" || exit 1; '
+                + 'chown "$owner" "$1" 2>/dev/null; [ -z "$top" ] || chown -R "$owner" "$top" 2>/dev/null; true', partial);
+            for (let offset = 0; offset < data.length; offset += UPLOAD_CHUNK_BYTES) {
+                let binary = '';
+                for (const byte of data.subarray(offset, offset + UPLOAD_CHUNK_BYTES))
+                    binary += String.fromCharCode(byte);
+                await sh('printf %s "$2" | base64 -d >> "$1"', partial, btoa(binary));
+            }
+            const moved = await sh('actual=$(sha256sum "$1" | cut -d" " -f1); '
+                + 'if [ "$actual" != "$3" ]; then echo "checksum mismatch: got $actual" >&2; exit 3; fi; '
+                + 'mv -f "$1" "$2" && realpath "$2"', partial, path, sha256);
+            return { path: moved.stdout.trim(), size: data.length, sha256 };
+        }
+        catch (error) {
+            // Best effort: the original failure is what the caller needs to see.
+            await exec(agentId, ['rm', '-f', partial]).catch(() => undefined);
+            throw error;
+        }
+    };
     const client = {
         ...createDeveloperApi(json, bytes, artifactSelectors),
         listModels: async () => {
@@ -758,7 +806,8 @@ export function createZooworkClient(cfg = {}) {
             return data.runs ?? [];
         },
         wake: (agentId, input) => json(`${agents(agentId)}/wake`, { method: 'POST', body: JSON.stringify(input) }),
-        exec: (agentId, args) => json(`${agents(agentId)}/exec`, { method: 'POST', body: JSON.stringify({ args }) }),
+        exec,
+        uploadFile,
         listEnvironments: async (opts = {}) => {
             const data = await json(`/environments${query({ page: opts.page })}`);
             return data.environments ?? [];

package/dist/developer-api.d.ts

@@ -157,10 +157,22 @@ export interface WebhookBatchRedeliveryInput {
     limit?: number;
 }
 export interface DeveloperApi {
+    /**
+     * @deprecated The hosted service does not enable the workspace Files routes; this call
+     * fails with HTTP 501 or 502. Ask the Agent to publish an Artifact and download that.
+     */
     getWorkspaceFile(agentId: string, path: string, opts?: {
         showHidden?: boolean;
     }): Promise<WorkspaceFile>;
+    /**
+     * @deprecated The hosted service does not enable the workspace Files routes; this call
+     * fails with HTTP 501 or 502. Use `uploadFile` to send a file to an Agent.
+     */
     writeWorkspaceFile(agentId: string, path: string, content: string): Promise<ApiObject>;
+    /**
+     * @deprecated The hosted service does not enable the workspace Files routes; this call
+     * fails with HTTP 501 or 502. Ask the Agent to publish an Artifact and download that.
+     */
     getWorkspaceFileContent(agentId: string, path: string, opts?: {
         download?: boolean;
     }): Promise<Uint8Array>;

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