@zoowork-ai/sdk 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -3,7 +3,20 @@
 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.
 
-## Unreleased
+## 0.10.0 — 2026-10-03
+
+- Add Files, read-only Agent Database, Usage, Run Output, action paging/detail and Agent webhook management helpers.
+- Add typed MCP confirmation, active Session creation and configuration concurrency metadata.
+- Align onboarding and capability examples with Platform Project keys.
+
+### Known service and documentation limitations
+
+Verified against production on 2026-10-03; these are not resolved by this SDK release:
+
+- Workspace Files read/write APIs return HTTP 502 with both Platform and legacy keys ([ecap #4006](https://github.com/SerendipityOneInc/ecap-workspace/issues/4006)).
+- Legacy keys cannot update or remove visible global Skill assignments on their own Agents; Platform keys succeed ([ecap #4007](https://github.com/SerendipityOneInc/ecap-workspace/issues/4007)).
+- Published Authentication URLs redirect to Quickstart, including the AI Markdown entry ([docs #56](https://github.com/SerendipityOneInc/zoowork-agents-docs/issues/56)).
+- Agent Database reads depend on deployment support. The production viewer was disabled, so its successful read path has not been validated.
 
 ## 0.9.0 — 2026-10-01
 
@@ -23,7 +36,7 @@ day the behaviour was verified, not the day it was written.
 - **The webhook event vocabulary.** `WEBHOOK_EVENT_TYPES` lists the sixteen types Engine
   delivers today, with a `data` shape per type behind `WebhookEventFor<T>` and
   `knownWebhookEvent()`. `WEBHOOK_SCHEDULE_CONFIG_EVENT_TYPES` declares the five schedule
-  configuration events whose server side is not deployed yet. A type the release does not know
+  configuration events for schedule configuration changes. A type the release does not know
   passes through with its raw `type` and `data` instead of throwing, so a receiver stays
   forward compatible.
 - Fixed cross-language signing vectors in `src/__vectors__/webhook-vectors.json`, copied verbatim
@@ -39,9 +52,8 @@ day the behaviour was verified, not the day it was written.
 
 ### Changed
 
-- Local E2E checks accept Platform `zwp_live_` keys as well as legacy `zct_` keys. Production
-  checks require an explicit URL and confirmation, and record their scope separately from
-  staging checks. The SDK already accepts Platform keys without a client API change.
+- Local E2E checks accept Platform Project keys. Production checks require an explicit URL
+  and confirmation, and record their scope separately from staging checks.
 - Live smoke tests select only selectable catalog models.
 
 ## 0.8.0 — 2026-09-20
@@ -220,8 +232,7 @@ No runtime change — comments only.
   - `createZooclawClient` → `createZooworkClient`; `ZooclawClient`, `ZooclawError`,
     `ZooclawAuth`, `ZooclawConfig` → `Zoowork*`.
   - `ZOOCLAW_API_KEY` / `ZOOCLAW_BASE_URL` → `ZOOWORK_API_KEY` / `ZOOWORK_BASE_URL`.
-- Server-side identifiers are unchanged: API keys still start with `zct_`, and skill or
-  environment names the API returns (e.g. `zooclaw-tts`) are whatever the server says.
+- Server-side identifiers and resource names remain opaque.
 
 ## 0.3.4 — 2026-08-25
 

package/README.md

@@ -10,9 +10,7 @@ npm install @zoowork-ai/sdk
 
 ## Quickstart
 
-Platform Project keys (`zwp_live_...`) and existing Work tokens (`zct_...`) both work with `apiKey`. Platform scopes Agent and Session access to the key’s Project and requires initialized Org billing and bound owner credentials. Rebind the key after signing in when the API requests it.
-
-Create a Project key in Platform, or a Work token under **Settings → API Keys** in the ZooWork App. Secrets are shown once at creation. Keep them server-side: Platform keys carry Project scope, while Work tokens use the existing organization authorization contract.
+Create a Project API key in [ZooWork Platform](https://platform.zoowork.ai). The secret is shown once. Save it as `ZOOWORK_API_KEY` on your server. Agent and Session access is scoped to the key's Project. Initialize Organization billing and bind owner credentials; sign in and rebind when the API requests it.
 
 ```ts
 import { createZooworkClient } from '@zoowork-ai/sdk'
@@ -68,12 +66,6 @@ separately.
 
 An explicit option always beats the environment variable.
 
-> **Finding the agent you built in the app.** The first path segment of a ZooWork chat URL
-> (`/chat/<32-hex>/sessions/…`) is a *workspace* id, not an `agt_…`. Resolve it with
-> `zc.listAgents({ labels: { workspace_id: '<32-hex>' } })`; use the pagination patterns
-> below to read one page or traverse every match. Scope is `owner_uid AND org_id` — an agent a *colleague*
-> created in your org is fetchable by id but will not appear in your list.
-
 > **Wait on `status.desired_state`, never on `status.actual_state`.**
 > `actual_state` reports chat-channel connectivity. An API-only agent has no channels,
 > but its projection depends on the channel-status capability: a GET can report `active`
@@ -155,30 +147,9 @@ must authenticate the user and authorize the session; `actor.ref` does neither.
 isolate the shared agent's sandbox files or erase a session's previous context. Omit `actor`
 to use the owner; IM sessions reject it. See the field's SDK comment for input constraints.
 
-## Bring your own skill
-
-A skill is a zip. One upload creates the skill *and* its first version; `putAgentSkill` attaches it.
-
-```ts
-import { readFile } from 'node:fs/promises'
-
-const skill = await zc.uploadSkill(await readFile('market-research.zip'), { scope: 'org' })
-await zc.putAgentSkill(agent.agent_id, skill.skill_id)
-```
-
-The zip's single top-level directory must be named exactly like the `name` in its `SKILL.md`
-frontmatter — `market-research/SKILL.md` declaring `name: market-research`. A mismatch is a 400,
-and it is the first one nearly everyone gets. `scope` is `org` or `personal`; the preinstalled
-`global` skills are listable but not installable with an API key, so this is the only way to
-control what a skill says. `uploadSkillVersion` publishes an update, and agents that installed it
-unpinned follow along without another `putAgentSkill`.
+## Agent Skills
 
-`uploadSkillVersion` returns a `SkillVersionRecord` with `version` and `state`, not the
-`latest_version` and `status` of the `SkillRecord` returned by `uploadSkill`. This return
-contract is source-reviewed, not a new live recording. On initial create, put the description
-in the zip's frontmatter: the gateway drops the `description` option. Version uploads can
-use that override. A successful create retried under the same name can return `409 skill_exists`;
-read back first. Version uploads deduplicate identical content for the same skill, not HTTP keys.
+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.
 
 ## Schedules, wake and exec
 
@@ -249,20 +220,7 @@ Approval response fields are source-reviewed, not end-to-end verified: read `req
 `allowed_decisions` and optional timeout/resolution fields defensively. `signaled: true` means
 the resolution was accepted; a returned `status: 'pending'` is not completed execution.
 
-`listEnvironments`, `getEnvironment`, `createEnvironment`, `createEnvironmentVersion`,
-`getEnvironmentVersion` and `archiveEnvironment` manage prebuilt sandbox images (apt/npm/pip
-packages, files, a build script, and an outbound allowlist). Two facts worth having before you
-start: an agent's Environment **freezes on its first sandbox creation** — after that every change
-is `409 environment_locked`, and stopping the agent does not clear it — and sandbox networking
-defaults to unrestricted unless the Environment declares `networking: { type: 'limited' }`.
-
-Build polling must have a deadline and handle `partial_ready`: some resource classes can be
-ready while others are building or failed. `getEnvironmentVersion(id, version, { resourceClass:
-'starter' })` selects one class; omitting the option keeps the aggregate read. Re-read the
-aggregate before concluding the build is fully ready. These details are source-reviewed.
-
-Channel callers must not use `allow_from` as an access-control list: the public gateway ignores
-it. Use supported `dm_policy` settings.
+Platform uses its managed Environment. Root Environment administration and Channel binding return `404 service_api.not_found` for Project keys. An exported method does not expand a key's permissions.
 
 ## Artifacts and the system prompt
 
@@ -291,7 +249,9 @@ and answers the new pin plus the version bump it cost.
 
 Verification needs the **raw request bytes**. `express.json()` and most framework body parsers
 consume them, and a `JSON.parse` → `JSON.stringify` round trip does not reproduce them byte for
-byte, so read the body before anything else touches it:
+byte, so read the body before anything else touches it. The example requires your
+application to supply `acceptOnce`, an atomic durable insert plus work-item enqueue, before it
+returns 204. A worker processes that item separately:
 
 ```ts
 import { createServer } from 'node:http'
@@ -315,12 +275,15 @@ createServer(async (req, res) => {
     throw error
   }
 
-  // Acknowledge first, then do the work: the sender retries a slow or failed response, and
-  // `event.id` is stable across retries, so it is also your deduplication key.
+  // Validate identity, then atomically persist the event and a durable work item.
+  // Implement acceptOnce with a unique webhook-id; a duplicate is successful too.
+  if (event.id !== req.headers['webhook-id']) { res.writeHead(400).end(); return }
+  try { await acceptOnce(event.id, event) } catch { res.writeHead(503).end(); return }
   res.writeHead(204).end()
 
+  // Dispatch this switch in the durable worker.
   const known = knownWebhookEvent(event)
-  if (!known) return // a type this release does not know: already acknowledged, ignore it
+  if (!known) return // keep unknown events accepted without side effects
   switch (known.type) {
     case 'run.finished':
       console.log(known.data.run_id, known.data.status)
@@ -363,7 +326,7 @@ Four more things worth knowing:
   resolved to one of its values: choosing would be a guess about which send arrived. The Python
   SDK rejects it too.
 - **`unwrapWebhook` checks six fields and no more** — `object`, `id`, `type`, `schema_version`,
-  `created_at`, `data` — so a field or event type a later Engine release adds is not a reason to
+  `created_at`, `data` — so a field or event type a later API release adds is not a reason to
   drop a delivery. `schema_version` must be a number with an **integer value**: `1` and `1.0` both
   pass, since JSON has one numeric type and they are the same number, while `1.5` is rejected with
   `invalid_payload`. The Python SDK reaches the same verdict on the same envelope.
@@ -374,7 +337,7 @@ Four more things worth knowing:
 it extends `Error`, while the Python SDK makes it a subclass of its own `ZooworkError` carrying a
 400. Match on `code`, and do not port `instanceof` checks between the two.
 
-You do not have to use this SDK to verify. Engine emits plain
+You do not have to use this SDK to verify. ZooWork emits plain
 [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks), so the official
 library for any language works with the same `whsec_` secret and the same raw body — npm
 [`standardwebhooks`](https://www.npmjs.com/package/standardwebhooks), PyPI
@@ -439,3 +402,39 @@ before creating the GitHub Release when live verification is required. Use
 ## License
 
 MIT
+
+## Developer API helpers
+
+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'],
+}, 'register-hook-v1')
+// Save signing_secret securely when present; an idempotent replay can return null.
+const hooks = await zc.listAgentWebhooks(agentId) // hooks.webhooks
+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
+verbatim. `getApproval` and `getCustomToolCall` read terminal as well as pending actions.
+
+Agent webhook methods include get/update/delete, `rotateAgentWebhookSecret`, `testAgentWebhook`,
+`getAgentWebhookEvent`, delivery list/detail and single/batch redelivery. Pass a stable idempotency
+key to create, rotation, test and redelivery. A 202 receipt confirms queuing; query delivery
+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.

package/dist/client.d.ts

@@ -1,13 +1,13 @@
 /**
  * ZooWork Managed Agents SDK — core client. Developer Preview.
  *
- * Authenticate with your organization API key (`zct_…`). It carries full tenant
- * authority, so it is SERVER-SIDE ONLY: never ship it in a browser or mobile bundle.
+ * Create a Project API key at https://platform.zoowork.ai. Keep it server-side: never ship it in a browser or mobile bundle.
  *
  * IDs are opaque strings and unknown response fields must be ignored — both are
  * forward-compatibility rules, not suggestions. Errors surface an `error.type`; match on
  * that, never on the message text.
  */
+import { type DeveloperApi } from './developer-api.js';
 import { type SessionEvent } from './events.js';
 /**
  * The production API base URL — the default. You should not need to set this:
@@ -22,9 +22,9 @@ export type ZooworkAuth = {
 };
 export interface ZooworkConfig {
     /**
-     * Your API key (`zct_...`). Defaults to `ZOOWORK_API_KEY`.
+     * Your Platform Project API key (`zwp_live_...`). Defaults to `ZOOWORK_API_KEY`.
      *
-     * Server-side only: it authenticates as your whole organization, not as one end user.
+     * Server-side only: access is scoped to the selected Project. Authorize application users separately.
      */
     apiKey?: string;
     /**
@@ -115,6 +115,8 @@ export declare class ZooworkError extends Error {
 export interface Ownership {
     owner_uid: string;
     org_id: string;
+    project_id?: string | null;
+    visibility?: 'private' | 'project';
 }
 export interface ModelInfo {
     model: string;
@@ -143,6 +145,9 @@ export interface McpContextConfig {
 }
 export interface McpToolPermissionOverride {
     permission: McpToolPermission;
+    /** True requires permission: 'always_ask' and a decision for each call, even with a persistent grant.
+     * Only allow-once or deny is offered. False/omission retains permission policy behavior. */
+    requireConfirmation?: boolean;
 }
 /**
  * One remote MCP server, declared as `resource.mcp[]` on create or update.
@@ -298,10 +303,15 @@ export interface AgentResource {
             seed_policy?: string;
         }[];
     };
-    skills?: {
+    skills?: (({
         skill_id: string;
+        name?: string;
+    } | {
+        name: string;
+        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.
@@ -655,6 +665,7 @@ export interface AgentRecord {
     environment_locked_at?: string | null;
     status?: AgentStatus;
     ownership?: Ownership;
+    sandbox_resource_class?: string;
     [k: string]: unknown;
 }
 /**
@@ -725,6 +736,10 @@ export interface SessionRecord {
     pending_approvals?: number;
     /** Pending application-executed custom-tool count on getSession. */
     pending_custom_tool_calls?: number;
+    pending_approval_ids?: string[];
+    pending_approval_ids_complete?: boolean;
+    pending_custom_tool_call_ids?: string[];
+    pending_custom_tool_call_ids_complete?: boolean;
     /**
      * `running` on a `createSession` receipt, nullable on `getSession`, and absent from
      * `listSessions` rows. This is not the run outcome; read {@link SessionRecord.run_status}
@@ -735,6 +750,8 @@ export interface SessionRecord {
     archived?: boolean;
     /** Present on filtered pages only when `includeDeleted` was requested. */
     deleted?: boolean;
+    idle_compaction?: boolean | null;
+    pinned_config_version?: number | null;
     runtime_mode?: 'active' | 'preview' | 'authoring' | 'evaluation' | string;
     config_version?: number;
     updated_at?: string;
@@ -940,12 +957,13 @@ export interface ScheduleUpdate {
  *  - `scheduleId` is the FULLY-QUALIFIED name `cron/{computer_id}/{agent_id}/{schedule_id}`, not
  *    the id you chose. Your id is `name`.
  *
- * The three responses also disagree with each other: `POST` answers with only snake_case
- * `schedule_name`; `GET /schedules/{id}` answers the camelCase projection below; `GET /schedules`
+ * Create receipts include the public `schedule_id` and snake_case `schedule_name`; `GET /schedules/{id}` answers the camelCase projection below; `GET /schedules`
  * answers the raw Temporal describe (`spec` / `state` / `memo` / `next_action_times`) with the
  * camelCase projection merged on top. Read defensively and match on what you find.
  */
 export interface ScheduleRecord {
+    /** Public opaque id, also present on create receipts. */
+    schedule_id?: string;
     /** FULLY-QUALIFIED: `cron/{computer_id}/{agent_id}/{schedule_id}`. Not the id you passed in. */
     scheduleId?: string;
     /** The `schedule_id` you chose. This is the one you pass back to get/update/delete. */
@@ -1016,6 +1034,9 @@ export interface ScheduleRecord {
 export interface ScheduleRun {
     /** Which projection this row came from. Decides which of the field groups below is populated. */
     source?: 'temporal' | 'run_projection' | string;
+    linked_by?: string;
+    run_id?: string;
+    trigger?: string;
     /** Present only when a session can be associated with this fire. */
     session_id?: string;
     /** Un-qualified `schedule_id`. */
@@ -1043,6 +1064,9 @@ export type ApprovalDecision = 'allow-once' | 'allow-always' | 'deny';
  * completion of the tool or run. Verify the resulting state separately.
  */
 export interface ApprovalRecord {
+    run_id?: string;
+    tool_call_id?: string;
+    resolution_channel?: string;
     approval_id?: string;
     session_id?: string;
     tool_name?: string;
@@ -1063,6 +1087,8 @@ export interface ApprovalRecord {
 export type CustomToolCallStatus = 'pending' | 'completed' | 'timeout' | 'cancelled' | string;
 /** One application-executed custom-tool call. Unknown response fields are preserved. */
 export interface CustomToolCallRecord {
+    run_id?: string;
+    resolution_channel?: string;
     call_id: string;
     session_id: string;
     tool_call_id: string;
@@ -1302,26 +1328,21 @@ export interface WakeResult {
     triggered: boolean;
 }
 export type { SessionEvent } from './events.js';
-export interface ZooworkClient {
+export interface ZooworkClient extends DeveloperApi {
     listModels(): Promise<ModelInfo[]>;
     /**
      * Create an agent. The gateway derives ownership from your API key and always skips the
      * interactive onboarding interview — the agent answers your first message directly.
-     * `ownership` is accepted for callers that talk to the engine without the gateway;
-     * through the gateway it is overwritten and can be omitted.
+     * Ownership is derived from the key. Omit caller-supplied ownership.
      */
     createAgent(input: {
         resource: AgentResource;
         ownership?: Ownership;
     }, idempotencyKey?: string): Promise<AgentRecord>;
     /**
-     * List the agents owned by your key's bound user (engine query: `owner_uid AND org_id`,
-     * both injected by the gateway). `labels` filters on declared labels — e.g.
-     * `{ labels: { workspace_id: '…' } }` resolves an app workspace id (the first path
-     * segment of a ZooWork chat URL) to its agent. Page size is fixed at 100 by the engine.
-     *
-     * Note the scope is `owner_uid AND org_id`: an agent a colleague created in your org is
-     * fetchable by `getAgent` but will not appear here.
+     * List Agents within the key's Project and applicable owner visibility. Labels filter
+     * declared labels, and page size is 100. Reads by id still recheck authorization;
+     * a colleague's Agent is not automatically accessible.
      *
      * `await listAgents()` returns one {@link AgentPage}; read `.data` for its agents and
      * `.next_page` / `.hasNextPage()` for continuation. `for await (const agent of listAgents())`
@@ -1329,7 +1350,8 @@ export interface ZooworkClient {
      */
     listAgents(opts?: AgentListParams): AgentPagePromise;
     getAgent(agentId: string): Promise<AgentRecord>;
-    /** PUT declared sections; bumps config_version on EVERY call — gate on drift, don't blind-retry. */
+    /** 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. */
     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.
@@ -1591,6 +1613,8 @@ export interface ZooworkClient {
     createSession(agentId: string, input: {
         initial_events?: OutboundEvent[];
         metadata?: Record<string, unknown>;
+        runtime_mode?: 'active';
+        idle_compaction?: boolean | null;
     }, idempotencyKey?: string): Promise<SessionRecord>;
     getSession(agentId: string, sessionId: string, opts?: {
         history?: boolean;
@@ -1678,6 +1702,7 @@ export interface ZooworkClient {
     /** Pending calls only. Any other status is rejected by the API. */
     listCustomToolCalls(agentId: string, opts?: {
         status?: 'pending';
+        sessionId?: string;
     }): Promise<CustomToolCallRecord[]>;
     /**
      * Return one call's result. A pending call answers 202/signaled:true but stays pending until
@@ -1700,6 +1725,7 @@ export interface ZooworkClient {
      */
     listApprovals(agentId: string, opts?: {
         status?: 'pending';
+        sessionId?: string;
     }): Promise<ApprovalRecord[]>;
     /** Resolve one approval. `decision` is exactly one of allow-once / allow-always / deny. */
     resolveApproval(agentId: string, approvalId: string, input: {
@@ -1857,7 +1883,7 @@ export interface ZooworkClient {
  * Create a client.
  *
  * ```ts
- * const zc = createZooworkClient({ apiKey: 'zct_...' })
+ * const zc = createZooworkClient({ apiKey: 'zwp_live_...' })
  * const zc = createZooworkClient()            // reads ZOOWORK_API_KEY
  * ```
  *

package/dist/client.js

@@ -1,13 +1,13 @@
 /**
  * ZooWork Managed Agents SDK — core client. Developer Preview.
  *
- * Authenticate with your organization API key (`zct_…`). It carries full tenant
- * authority, so it is SERVER-SIDE ONLY: never ship it in a browser or mobile bundle.
+ * Create a Project API key at https://platform.zoowork.ai. Keep it server-side: never ship it in a browser or mobile bundle.
  *
  * IDs are opaque strings and unknown response fields must be ignored — both are
  * forward-compatibility rules, not suggestions. Errors surface an `error.type`; match on
  * that, never on the message text.
  */
+import { createDeveloperApi } from './developer-api.js';
 import { parseSSE, isObj } from './sse.js';
 import { normalizeEvent } from './events.js';
 /**
@@ -143,7 +143,7 @@ function httpError(res, text) {
  * Create a client.
  *
  * ```ts
- * const zc = createZooworkClient({ apiKey: 'zct_...' })
+ * const zc = createZooworkClient({ apiKey: 'zwp_live_...' })
  * const zc = createZooworkClient()            // reads ZOOWORK_API_KEY
  * ```
  *
@@ -165,7 +165,7 @@ export function createZooworkClient(cfg = {}) {
             })());
     if (!auth) {
         throw new Error('No ZooWork API key. Pass createZooworkClient({ apiKey }) or set ZOOWORK_API_KEY. ' +
-            'Keys look like zct_… and are issued by an organization administrator.');
+            'Create a Project API key at https://platform.zoowork.ai.');
     }
     const bearer = 'serviceToken' in auth ? auth.serviceToken : auth.apiKey;
     /**
@@ -282,13 +282,20 @@ export function createZooworkClient(cfg = {}) {
         const own = projection.ownership;
         if (!own?.owner_uid || !own.org_id) {
             throw new ZooworkError(500, `agent ${agentId} projection carries no ownership — cannot derive the owner_uid/org_id ` +
-                'selectors the artifact routes require', 'ownership_unavailable');
+                'selectors the file and artifact routes require', 'ownership_unavailable');
         }
         const sel = { owner_uid: own.owner_uid, org_id: own.org_id };
         ownershipByAgent.set(agentId, sel);
         return sel;
     };
+    const bytes = async (path) => {
+        const res = await doFetch(`${base}${path}`, { headers: { Authorization: `Bearer ${bearer}` } });
+        if (!res.ok)
+            throw httpError(res, await res.text());
+        return new Uint8Array(await res.arrayBuffer());
+    };
     const client = {
+        ...createDeveloperApi(json, bytes, artifactSelectors),
         listModels: async () => {
             const data = await json('/models');
             return Array.isArray(data) ? data : (data.models ?? []);
@@ -668,7 +675,7 @@ export function createZooworkClient(cfg = {}) {
             }
         },
         listCustomToolCalls: async (agentId, opts = {}) => {
-            const data = await json(`${agents(agentId)}/custom_tool_calls${query({ status: opts.status })}`);
+            const data = await json(`${agents(agentId)}/custom_tool_calls${query({ status: opts.status, session_id: opts.sessionId })}`);
             return data.custom_tool_calls ?? [];
         },
         resolveCustomToolCall: (agentId, callId, input) => json(`${agents(agentId)}/custom_tool_calls/${encodeURIComponent(callId)}/result`, {
@@ -676,7 +683,7 @@ export function createZooworkClient(cfg = {}) {
             body: JSON.stringify(input),
         }),
         listApprovals: async (agentId, opts = {}) => {
-            const data = await json(`${agents(agentId)}/approvals${query({ status: opts.status })}`);
+            const data = await json(`${agents(agentId)}/approvals${query({ status: opts.status, session_id: opts.sessionId })}`);
             return data.approvals ?? [];
         },
         resolveApproval: (agentId, approvalId, input) => json(`${agents(agentId)}/approvals/${encodeURIComponent(approvalId)}/resolve`, {

package/dist/developer-api.d.ts

@@ -0,0 +1,200 @@
+import type { ApprovalRecord, CustomToolCallRecord, Ownership } from './client.js';
+import type { WebhookEventType } from './webhooks.js';
+/** Response fields retain their API spelling; unknown additions are preserved. */
+export type ApiObject = Record<string, unknown>;
+export interface CursorOptions {
+    cursor?: string;
+    limit?: number;
+}
+export interface ActionListOptions extends CursorOptions {
+    status?: 'pending';
+    sessionId?: string;
+}
+export interface ApprovalPage extends ApiObject {
+    approvals: ApprovalRecord[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+export interface CustomToolCallPage extends ApiObject {
+    custom_tool_calls: CustomToolCallRecord[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+export interface WorkspaceFileEntry extends ApiObject {
+    name: string;
+    type: string;
+    size?: number;
+    updated_at?: string;
+}
+export type WorkspaceFile = (ApiObject & {
+    path: string;
+    content: string;
+}) | (ApiObject & {
+    path: string;
+    entries: WorkspaceFileEntry[];
+});
+export interface AgentDatabase extends ApiObject {
+    status: 'not_provisioned' | 'ready';
+    tables?: {
+        name: unknown;
+        kind: unknown;
+    }[];
+}
+export interface AgentDatabaseRows extends ApiObject {
+    status: 'not_provisioned' | 'ready';
+    table?: string;
+    schema?: unknown[][];
+    columns?: string[];
+    rows?: unknown[][];
+    limit?: number;
+    offset?: number;
+}
+export interface UsageOptions {
+    range?: '24h' | '7d' | '30d';
+    timezone?: string;
+    groupBy?: 'session' | 'api_key';
+    view?: 'groups' | 'records' | 'both';
+    sessionId?: string;
+    apiKeyId?: string;
+    rootSessionId?: string;
+    attribution?: 'exact' | 'shared' | 'non_api' | 'unattributed';
+    page?: number;
+    perPage?: number;
+    asOf?: string;
+    snapshot?: string;
+    cursor?: string;
+}
+export interface UsageResult extends ApiObject {
+    groups?: ApiObject[];
+    records?: ApiObject[];
+}
+export interface RunOutputArtifact extends ApiObject {
+    artifact_id: string | null;
+    name: string;
+    content_type: string;
+    size: number;
+}
+export interface RunOutputItem extends ApiObject {
+    seq: number;
+    kind: string;
+    source: string;
+    text?: string;
+    artifacts: RunOutputArtifact[];
+}
+export interface RunOutput extends ApiObject {
+    run: ApiObject;
+    items: RunOutputItem[];
+    has_more: boolean;
+    next_cursor: string | null;
+    output_complete: boolean;
+}
+export interface AgentWebhookInput {
+    url: string;
+    event_types: Exclude<WebhookEventType, 'webhook.test'>[];
+    description?: string | null;
+    session_scope?: 'api' | 'all';
+    enabled?: boolean;
+}
+export interface AgentWebhookEndpoint extends ApiObject {
+    id: string;
+    url?: string;
+    event_types?: string[];
+    description?: string | null;
+    session_scope?: string;
+    enabled?: boolean;
+}
+export interface AgentWebhookPage extends ApiObject {
+    webhooks: AgentWebhookEndpoint[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+export interface AgentWebhookCreated extends ApiObject {
+    endpoint: AgentWebhookEndpoint;
+    signing_secret: string | null;
+    signing_secret_version: number;
+    signing_secret_available: boolean;
+}
+export interface AgentWebhookSecretRotation extends ApiObject {
+    endpoint_id: string;
+    signing_secret: string | null;
+    signing_secret_version: number;
+    signing_secret_available: boolean;
+    previous_versions?: unknown[];
+}
+export interface WebhookDeliveryOptions extends CursorOptions {
+    status?: 'pending' | 'in_flight' | 'succeeded' | 'dead' | 'cancelled';
+    eventType?: string;
+    eventId?: string;
+    sessionId?: string;
+    runId?: string;
+    scheduleId?: string;
+}
+export interface WebhookDeliveryPage extends ApiObject {
+    deliveries: ApiObject[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+/** These receipts acknowledge queuing, not receiver or business processing. */
+export interface WebhookTestReceipt extends ApiObject {
+    object: 'webhook_test';
+    endpoint_id: string;
+    receipt_id: string;
+}
+export interface WebhookRedeliveryReceipt extends ApiObject {
+    object: 'webhook_redelivery';
+    delivery_id: string;
+    round: number;
+    deadline_at: string;
+}
+export interface WebhookBatchRedeliveryReceipt extends ApiObject {
+    object: 'webhook_redelivery_batch';
+    count: number;
+}
+export interface WebhookBatchRedeliveryInput {
+    status?: 'dead';
+    since?: string | null;
+    event_types?: string[] | null;
+    limit?: number;
+}
+export interface DeveloperApi {
+    getWorkspaceFile(agentId: string, path: string, opts?: {
+        showHidden?: boolean;
+    }): Promise<WorkspaceFile>;
+    writeWorkspaceFile(agentId: string, path: string, content: string): Promise<ApiObject>;
+    getWorkspaceFileContent(agentId: string, path: string, opts?: {
+        download?: boolean;
+    }): Promise<Uint8Array>;
+    getAgentDatabase(agentId: string): Promise<AgentDatabase>;
+    getAgentDatabaseRows(agentId: string, tableName: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<AgentDatabaseRows>;
+    getUsage(opts?: UsageOptions): Promise<UsageResult>;
+    getRunOutput(agentId: string, sessionId: string, runId: string, opts?: CursorOptions): Promise<RunOutput>;
+    getApproval(agentId: string, approvalId: string): Promise<ApprovalRecord>;
+    getCustomToolCall(agentId: string, callId: string): Promise<CustomToolCallRecord>;
+    listApprovalPage(agentId: string, opts?: ActionListOptions): Promise<ApprovalPage>;
+    listCustomToolCallPage(agentId: string, opts?: ActionListOptions): Promise<CustomToolCallPage>;
+    listAgentWebhooks(agentId: string, opts?: CursorOptions): Promise<AgentWebhookPage>;
+    createAgentWebhook(agentId: string, input: AgentWebhookInput, idempotencyKey: string): Promise<AgentWebhookCreated>;
+    getAgentWebhook(agentId: string, webhookId: string): Promise<AgentWebhookEndpoint>;
+    updateAgentWebhook(agentId: string, webhookId: string, input: Partial<AgentWebhookInput>): Promise<AgentWebhookEndpoint>;
+    deleteAgentWebhook(agentId: string, webhookId: string): Promise<void>;
+    rotateAgentWebhookSecret(agentId: string, webhookId: string, input: {
+        revoke_previous_after: 0 | 86400;
+    }, idempotencyKey: string): Promise<AgentWebhookSecretRotation>;
+    testAgentWebhook(agentId: string, webhookId: string, idempotencyKey: string): Promise<WebhookTestReceipt>;
+    getAgentWebhookEvent(agentId: string, eventId: string): Promise<ApiObject>;
+    listAgentWebhookDeliveries(agentId: string, webhookId: string, opts?: WebhookDeliveryOptions): Promise<WebhookDeliveryPage>;
+    getAgentWebhookDelivery(agentId: string, webhookId: string, deliveryId: string): Promise<ApiObject>;
+    redeliverAgentWebhookDelivery(agentId: string, webhookId: string, deliveryId: string, idempotencyKey: string): Promise<WebhookRedeliveryReceipt>;
+    redeliverAgentWebhookDeliveries(agentId: string, webhookId: string, input: WebhookBatchRedeliveryInput, idempotencyKey: string): Promise<WebhookBatchRedeliveryReceipt>;
+}
+type Request = <T>(path: string, init?: {
+    method?: string;
+    body?: string;
+    headers?: Record<string, string>;
+}) => Promise<T>;
+/** Uses the same authentication/error transport as the existing client. Never retries writes. */
+export declare function createDeveloperApi(json: Request, bytes: (path: string) => Promise<Uint8Array>, selectors: (agentId: string) => Promise<Pick<Ownership, 'owner_uid' | 'org_id'>>): DeveloperApi;
+export {};

package/dist/developer-api.js

@@ -0,0 +1,42 @@
+const segment = encodeURIComponent;
+function query(params) {
+    const result = new URLSearchParams();
+    for (const [key, value] of Object.entries(params))
+        if (value !== undefined)
+            result.set(key, String(value));
+    return result.size ? `?${result}` : '';
+}
+function post(body, idempotencyKey) {
+    return { method: 'POST', body: JSON.stringify(body), ...(idempotencyKey !== undefined ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}) };
+}
+/** Uses the same authentication/error transport as the existing client. Never retries writes. */
+export function createDeveloperApi(json, bytes, selectors) {
+    const agent = (id) => `/agents/${segment(id)}`;
+    const webhooks = (id) => `${agent(id)}/webhooks`;
+    const endpoint = (id, webhookId) => `${webhooks(id)}/${segment(webhookId)}`;
+    return {
+        getWorkspaceFile: async (id, path, opts = {}) => json(`${agent(id)}/files${query({ ...await selectors(id), path, showHidden: opts.showHidden })}`),
+        writeWorkspaceFile: (id, path, content) => json(`${agent(id)}/files`, post({ path, content })),
+        getWorkspaceFileContent: async (id, path, opts = {}) => bytes(`${agent(id)}/files/content${query({ ...await selectors(id), path, download: opts.download })}`),
+        getAgentDatabase: (id) => json(`${agent(id)}/database`),
+        getAgentDatabaseRows: (id, table, opts = {}) => json(`${agent(id)}/database/tables/${segment(table)}/rows${query({ limit: opts.limit, offset: opts.offset })}`),
+        getUsage: (opts = {}) => json(`/usage${query({ range: opts.range, timezone: opts.timezone, group_by: opts.groupBy, view: opts.view, session_id: opts.sessionId, api_key_id: opts.apiKeyId, root_session_id: opts.rootSessionId, attribution: opts.attribution, page: opts.page, per_page: opts.perPage, as_of: opts.asOf, snapshot: opts.snapshot, cursor: opts.cursor })}`),
+        getRunOutput: (id, sid, rid, opts = {}) => json(`${agent(id)}/sessions/${segment(sid)}/runs/${segment(rid)}/output${query({ cursor: opts.cursor, limit: opts.limit })}`),
+        getApproval: (id, aid) => json(`${agent(id)}/approvals/${segment(aid)}`),
+        getCustomToolCall: (id, cid) => json(`${agent(id)}/custom_tool_calls/${segment(cid)}`),
+        listApprovalPage: (id, opts = {}) => json(`${agent(id)}/approvals${query({ status: opts.status, session_id: opts.sessionId, cursor: opts.cursor, limit: opts.limit ?? 50 })}`),
+        listCustomToolCallPage: (id, opts = {}) => json(`${agent(id)}/custom_tool_calls${query({ status: opts.status, session_id: opts.sessionId, cursor: opts.cursor, limit: opts.limit ?? 50 })}`),
+        listAgentWebhooks: (id, opts = {}) => json(`${webhooks(id)}${query({ cursor: opts.cursor, limit: opts.limit })}`),
+        createAgentWebhook: (id, input, key) => json(webhooks(id), post(input, key)),
+        getAgentWebhook: (id, wid) => json(endpoint(id, wid)),
+        updateAgentWebhook: (id, wid, input) => json(`${endpoint(id, wid)}/update`, post(input)),
+        deleteAgentWebhook: async (id, wid) => { await json(`${endpoint(id, wid)}/delete`, post({})); },
+        rotateAgentWebhookSecret: (id, wid, input, key) => json(`${endpoint(id, wid)}/rotate-secret`, post(input, key)),
+        testAgentWebhook: (id, wid, key) => json(`${endpoint(id, wid)}/test`, post({}, key)),
+        getAgentWebhookEvent: (id, eid) => json(`${webhooks(id)}/events/${segment(eid)}`),
+        listAgentWebhookDeliveries: (id, wid, opts = {}) => json(`${endpoint(id, wid)}/deliveries${query({ cursor: opts.cursor, limit: opts.limit, status: opts.status, event_type: opts.eventType, event_id: opts.eventId, session_id: opts.sessionId, run_id: opts.runId, schedule_id: opts.scheduleId })}`),
+        getAgentWebhookDelivery: (id, wid, did) => json(`${endpoint(id, wid)}/deliveries/${segment(did)}`),
+        redeliverAgentWebhookDelivery: (id, wid, did, key) => json(`${endpoint(id, wid)}/deliveries/${segment(did)}/redeliver`, post({}, key)),
+        redeliverAgentWebhookDeliveries: (id, wid, input, key) => json(`${endpoint(id, wid)}/deliveries/redeliver`, post(input, key)),
+    };
+}

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export { createZooworkClient, DEFAULT_BASE_URL, ZooworkError, type ZooworkClient
 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';
+export type { ApiObject, CursorOptions, ActionListOptions, ApprovalPage, CustomToolCallPage, WorkspaceFileEntry, WorkspaceFile, AgentDatabase, AgentDatabaseRows, UsageOptions, UsageResult, RunOutputArtifact, RunOutputItem, RunOutput, AgentWebhookInput, AgentWebhookEndpoint, AgentWebhookPage, AgentWebhookCreated, AgentWebhookSecretRotation, WebhookDeliveryOptions, WebhookDeliveryPage, WebhookTestReceipt, WebhookRedeliveryReceipt, WebhookBatchRedeliveryReceipt, WebhookBatchRedeliveryInput, DeveloperApi, } from './developer-api.js';

package/dist/secret-redaction.d.ts

@@ -0,0 +1,2 @@
+/** Fixture safety only; authentication treats keys as opaque values. */
+export declare function redactApiKeys(text: string, knownKey?: string): string;

package/dist/secret-redaction.js

@@ -0,0 +1,10 @@
+/** Fixture safety only; authentication treats keys as opaque values. */
+export function redactApiKeys(text, knownKey) {
+    let clean = text;
+    if (knownKey && knownKey.length >= 8)
+        clean = clean.split(knownKey).join('REDACTED');
+    return clean
+        .replace(/zwp_live_[A-Za-z0-9_-]{8,}/g, 'zwp_live_REDACTED')
+        .replace(/zct_[A-Za-z0-9_-]{8,}/g, 'zct_REDACTED')
+        .replace(/(Bearer )[A-Za-z0-9._~+/-]{8,}=*/g, '$1REDACTED');
+}

package/dist/webhooks.d.ts

@@ -46,10 +46,7 @@ export declare const WEBHOOK_EVENT_TYPES: readonly ["run.started", "run.finished
 /**
  * Schedule CONFIGURATION changes, as distinct from the fire events above.
  *
- * Declared here so a receiver can write the subscription and the handler now, but the server
- * side ships with Engine E5a and is NOT emitted yet — the projector currently retires such a
- * receipt as `unknown_source`. Do not read a delivered one of these as evidence the feature is
- * live; check the Engine release notes.
+ * Subscribe to these types for schedule configuration changes. Deliveries may be reordered.
  */
 export declare const WEBHOOK_SCHEDULE_CONFIG_EVENT_TYPES: readonly ["schedule.created", "schedule.updated", "schedule.paused", "schedule.resumed", "schedule.deleted"];
 export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number] | (typeof WEBHOOK_SCHEDULE_CONFIG_EVENT_TYPES)[number];
@@ -217,7 +214,7 @@ export interface WebhookScheduleFinishedData extends WebhookScheduleFireData {
 }
 /**
  * A schedule's configuration changed. See {@link WEBHOOK_SCHEDULE_CONFIG_EVENT_TYPES}: declared,
- * not yet delivered.
+ * delivered for schedule configuration changes.
  */
 export interface WebhookScheduleConfigData extends WebhookEventAttribution {
     /**

package/dist/webhooks.js

@@ -64,10 +64,7 @@ export const WEBHOOK_EVENT_TYPES = [
 /**
  * Schedule CONFIGURATION changes, as distinct from the fire events above.
  *
- * Declared here so a receiver can write the subscription and the handler now, but the server
- * side ships with Engine E5a and is NOT emitted yet — the projector currently retires such a
- * receipt as `unknown_source`. Do not read a delivered one of these as evidence the feature is
- * live; check the Engine release notes.
+ * Subscribe to these types for schedule configuration changes. Deliveries may be reordered.
  */
 export const WEBHOOK_SCHEDULE_CONFIG_EVENT_TYPES = [
     'schedule.created',

package/package.json

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