@zoowork-ai/sdk 0.10.2 → 0.11.1

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.1 — 2026-10-04
+
+- `uploadFile` no longer runs `chown` on the uploaded file or on directories it creates. The
+  sandbox workspace mount does not enforce ownership, and a staging check showed the Agent's
+  edit and write tools modify uploaded files without it. Existing calls remain compatible.
+
+## 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.

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

@@ -1321,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. */
@@ -1855,6 +1864,21 @@ 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`.
+     *
+     * 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,49 @@ 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 {
+            await sh('mkdir -p "$(dirname "$1")" && : > "$1"', 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 +801,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.2",
+  "version": "0.11.1",
   "description": "TypeScript SDK for the ZooWork Managed Agents API (Developer Preview)",
   "keywords": [
     "zoowork",