@zoowork-ai/sdk 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -3,6 +3,59 @@
 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.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
+
+### Added
+
+- **Webhook receiving.** `verifyWebhookSignature` and `unwrapWebhook` check a delivery's Standard
+  Webhooks signature over the raw body and hand back the envelope; `signWebhook` is exported so a
+  receiver can build a delivery for its own tests. The HMAC is WebCrypto, so the zero-runtime-
+  dependency guarantee holds and the functions are `async`. Headers can come from a fetch
+  `Headers`, a record in any casing, or Node's `IncomingHttpHeaders`. Failures throw
+  `ZooworkWebhookError` with a machine-readable `code` and a message that carries no secret,
+  signature or body.
+- **Rotation without a deploy.** `ZOOWORK_WEBHOOK_SECRET` accepts several secrets separated by
+  whitespace or commas, and a delivery signed under any of them verifies — the sender double-signs
+  for the length of the window. The Python SDK reads the variable identically, so one deployment's
+  configuration serves both. A `secret` passed explicitly is never split.
+- **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 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
+  from Engine's `packages/webhook-signing` and asserted three ways (an independent WebCrypto
+  computation, the recorded JSON, and this SDK). They are the compatibility contract with the
+  official `standardwebhooks` libraries; adding a vector is fine, editing one is not.
+
+### Fixed
+
+- `streamEvents()` cancels and releases its response reader when a consumer exits early,
+  including a loop that stops at `run.finished`. This prevents an open SSE connection from
+  keeping a Node.js consumer alive after its turn has completed.
+
+### Changed
+
+- 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
 
 ### Added
@@ -179,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,7 +10,7 @@ npm install @zoowork-ai/sdk
 
 ## Quickstart
 
-You need an API key (`zct_...`) issued for your organization — create one in the ZooWork App under **Settings → API Keys** (any personal org; enterprise orgs need the admin role), or ask your org admin for one. The secret is shown exactly once at creation. Keep it server-side: it authenticates as your whole organization, not as one end user.
+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'
@@ -66,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`
@@ -153,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
 
@@ -247,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
 
@@ -285,6 +245,106 @@ activation on its own — moving it is one explicit call, `upgradeSystemPrompt`,
 the agent's current `config_version` as a CAS (`409 config_version_changed` on a stale one)
 and answers the new pin plus the version bump it cost.
 
+## Receiving webhooks
+
+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. 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'
+import { knownWebhookEvent, unwrapWebhook, ZooworkWebhookError } from '@zoowork-ai/sdk'
+
+createServer(async (req, res) => {
+  const chunks: Buffer[] = []
+  for await (const chunk of req) chunks.push(chunk as Buffer)
+  const rawBody = Buffer.concat(chunks)
+
+  let event
+  try {
+    // Defaults to ZOOWORK_WEBHOOK_SECRET, or pass `secret: [newest, previous]` explicitly.
+    event = await unwrapWebhook({ headers: req.headers, rawBody })
+  } catch (error) {
+    if (error instanceof ZooworkWebhookError) {
+      console.warn('rejected webhook', error.code) // never carries the secret, signature or body
+      res.writeHead(400).end()
+      return
+    }
+    throw error
+  }
+
+  // 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 // keep unknown events accepted without side effects
+  switch (known.type) {
+    case 'run.finished':
+      console.log(known.data.run_id, known.data.status)
+      break
+    case 'approval.requested':
+      console.log(known.data.approval_id, known.data.tool_name)
+      break
+  }
+}).listen(3000)
+```
+
+`verifyWebhookSignature` is the same check without the parse, for a handler that wants the bytes.
+Both are `async`: the HMAC is WebCrypto (`crypto.subtle`), which is how this SDK verifies
+signatures with no runtime dependency and still runs in Workers, Deno and the browser.
+
+### Rotating the secret without a deploy
+
+`ZOOWORK_WEBHOOK_SECRET` accepts **several secrets**, separated by whitespace or commas. During a
+rotation window the sender signs under every active key, so a receiver that lists both accepts
+whichever one signed a given delivery:
+
+```sh
+ZOOWORK_WEBHOOK_SECRET="whsec_<new> whsec_<previous>"   # commas work too
+```
+
+Splitting is unambiguous because a secret is `whsec_` plus standard base64 of 32 bytes — no comma,
+no whitespace. The Python SDK reads the variable the same way, so one deployment's configuration
+serves both. A `secret` you pass explicitly is never split: a string is one secret, and several go
+in an array.
+
+Four more things worth knowing:
+
+- **The clock window is checked against the `webhook-timestamp` header, not the envelope's
+  `created_at`.** A retry of an old event carries a fresh timestamp and verifies; `created_at`
+  still says when the fact happened. The default tolerance is ±300s.
+- **A body over 16 KiB is refused before it is hashed** — the sender's own envelope ceiling.
+- **Unknown event types are normal.** New types ship within a schema version, and a receiver that
+  fails one only makes the sender retry it and then dead-letter it. Acknowledge and ignore.
+- **A repeated `webhook-id`, `webhook-timestamp` or `webhook-signature` header is rejected**, not
+  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 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.
+
+`ZooworkWebhookError.code` is the contract to match on — `invalid_secret`, `body_too_large`,
+`missing_header`, `invalid_header`, `timestamp_out_of_window`, `signature_mismatch`,
+`invalid_payload` — and those strings are identical in the Python SDK. The class shape is not: here
+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. 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
+[`standardwebhooks`](https://pypi.org/project/standardwebhooks/), or another of the ports. The
+fixed vectors in [`src/__vectors__/webhook-vectors.json`](src/__vectors__/webhook-vectors.json)
+are copied verbatim from Engine and are byte-compatible with all of them.
+
 ## Two helpers
 
 ```ts
@@ -342,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`, {