@zoowork-ai/sdk 0.4.0

package/dist/client.js

@@ -0,0 +1,622 @@
+/**
+ * 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.
+ *
+ * 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 { parseSSE, isObj } from './sse.js';
+import { normalizeEvent } from './events.js';
+/**
+ * The production API base URL — the default. You should not need to set this:
+ * `ZOOWORK_BASE_URL` overrides it, and so does the `baseUrl` option, only when you
+ * need to point at a different deployment.
+ */
+export const DEFAULT_BASE_URL = 'https://clawapi.ecap.gsmo.ai/service/v1';
+/**
+ * Read an environment variable without assuming a Node runtime.
+ *
+ * The SDK runs in Workers, Deno and browsers too, where `process` does not exist —
+ * touching it unguarded is a ReferenceError, not `undefined`.
+ */
+function readEnv(name) {
+    const proc = globalThis.process;
+    const value = proc?.env?.[name];
+    return value === undefined || value === '' ? undefined : value;
+}
+export class ZooworkError extends Error {
+    status;
+    /**
+     * The machine-readable error code. Match on this, never on the message.
+     *
+     * TWO VOCABULARIES, because there are two error envelopes — staging-verified 2026-08-07. The
+     * sessions/schedules/environments family answers `{ error: { type, message } }` with a bare code
+     * (`agent_not_running`, `session_archived`, `environment_not_ready`); the agents family answers
+     * `{ code, detail }` with a DOTTED one (`service_api.not_found`). Both land here, so a caller
+     * always gets something — but do not assume one spelling covers both, and prefer `status` when
+     * you only need the class of failure.
+     */
+    type;
+    constructor(status, message, type) {
+        super(message);
+        this.name = 'ZooworkError';
+        this.status = status;
+        if (type)
+            this.type = type;
+    }
+}
+/**
+ * Create a client.
+ *
+ * ```ts
+ * const zc = createZooworkClient({ apiKey: 'zct_...' })
+ * const zc = createZooworkClient()            // reads ZOOWORK_API_KEY
+ * ```
+ *
+ * Resolution order for both settings is the same: explicit argument, then environment
+ * variable, then (for `baseUrl` only) the built-in default.
+ *
+ * @throws if no API key can be resolved — a missing key is a setup mistake worth failing
+ *         loudly at construction rather than as a 401 on the first call.
+ */
+export function createZooworkClient(cfg = {}) {
+    const doFetch = cfg.fetch ?? ((input, init) => fetch(input, init));
+    const base = (cfg.baseUrl ?? readEnv('ZOOWORK_BASE_URL') ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const auth = cfg.auth ??
+        (cfg.apiKey !== undefined
+            ? { apiKey: cfg.apiKey }
+            : (() => {
+                const fromEnv = readEnv('ZOOWORK_API_KEY');
+                return fromEnv ? { apiKey: fromEnv } : undefined;
+            })());
+    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.');
+    }
+    const bearer = 'serviceToken' in auth ? auth.serviceToken : auth.apiKey;
+    /**
+     * TWO error envelopes, one ZooworkError shape, for every helper below.
+     *
+     * The API does not answer failures the same way everywhere — staging-verified 2026-08-07. Most
+     * families send `{ error: { type, message } }`; the agents family sends `{ code, detail }`.
+     * Reading only the first left every agent 404 with `type: undefined` and the message `HTTP 404`,
+     * so both are unpacked here. The codes stay verbatim (`not_found` vs `service_api.not_found`) —
+     * inventing a shared vocabulary would be this SDK guessing, which is what it exists not to do.
+     */
+    const readResponse = async (res, path) => {
+        const text = await res.text();
+        if (!res.ok) {
+            let msg = `HTTP ${res.status}`;
+            let type;
+            try {
+                const j = JSON.parse(text);
+                msg = j?.error?.message || j?.message || j?.detail || msg;
+                type = j?.error?.type ?? j?.code;
+            }
+            catch {
+                /* non-JSON error body → keep clean status */
+            }
+            throw new ZooworkError(res.status, msg, type);
+        }
+        if (!text)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new ZooworkError(res.status, `non-JSON response: ${path}`);
+        }
+    };
+    /**
+     * `signal` is forwarded to `fetch`, so a request can be cancelled WHILE IT IS IN FLIGHT.
+     * That matters because neither Node's `fetch` nor the Workers one has a default timeout:
+     * a gateway that accepts the connection and then stalls hangs the promise forever unless
+     * somebody hands it a signal. See `waitUntilRunning`, which bounds every poll with one.
+     */
+    const json = async (path, init = {}) => {
+        const headers = { ...init.headers, Authorization: `Bearer ${bearer}` };
+        if (init.body && !('Content-Type' in headers))
+            headers['Content-Type'] = 'application/json';
+        const res = await doFetch(`${base}${path}`, {
+            method: init.method,
+            body: init.body,
+            headers,
+            ...(init.signal ? { signal: init.signal } : {}),
+        });
+        return readResponse(res, path);
+    };
+    /**
+     * Multipart sibling of `json()`: same auth, same error envelope, but the body is a `FormData`
+     * and the SDK deliberately does NOT set `Content-Type`. The runtime has to set it, because
+     * only the runtime knows the boundary it generated — hand-writing
+     * `multipart/form-data` yourself produces a body the server cannot parse.
+     */
+    const multipart = async (path, form, init = {}) => {
+        const headers = { ...init.headers, Authorization: `Bearer ${bearer}` };
+        const res = await doFetch(`${base}${path}`, { method: init.method ?? 'POST', body: form, headers });
+        return readResponse(res, path);
+    };
+    const agents = (id) => `/agents/${encodeURIComponent(id)}`;
+    const sessions = (id) => `${agents(id)}/sessions`;
+    const schedules = (id) => `${agents(id)}/schedules`;
+    const environments = (id) => `/environments/${encodeURIComponent(id)}`;
+    const query = (params) => {
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(params))
+            if (v !== undefined)
+                q.set(k, String(v));
+        const qs = q.toString();
+        return qs ? `?${qs}` : '';
+    };
+    /**
+     * A zip from any of the three shapes callers actually hold. `Blob` exists in every runtime we
+     * target, so it is the one currency `FormData` always accepts.
+     *
+     * The cast is a typings artefact, not a runtime risk: lib.dom narrows `BlobPart`'s view branch
+     * to `ArrayBufferView<ArrayBuffer>`, which excludes a plain `Uint8Array` (whose buffer is
+     * `ArrayBufferLike`) — i.e. exactly what `fs.readFile` hands you.
+     */
+    const zipBlob = (zip) => zip instanceof Blob ? zip : new Blob([zip], { type: 'application/zip' });
+    const skillForm = (zip, opts) => {
+        const form = new FormData();
+        // `files[]` is the field name the Skills API expects — it is isomorphic to the Claude
+        // Skills API, and exactly one zip goes in it.
+        form.append('files[]', zipBlob(zip), opts.fileName ?? 'skill.zip');
+        if (opts.description !== undefined)
+            form.append('description', opts.description);
+        return form;
+    };
+    /** Interruptible sleep, so an aborted wait does not linger for the rest of its interval. */
+    const sleep = (ms, signal) => new Promise((resolve) => {
+        // Check first: `addEventListener('abort')` never fires on an ALREADY-aborted signal, so
+        // without this an abort that landed during the preceding request would sleep the whole
+        // interval before anyone noticed it.
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        let timer;
+        const done = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
+    /**
+     * `owner_uid` + `org_id` for the artifacts family, derived once per agent from its own
+     * projection. The engine requires both selectors on every artifact route and re-checks them
+     * against the agent's ownership; the gateway forwards the caller's query verbatim there
+     * (it injects selectors only on `GET /agents`), so the SDK has to supply them — and the
+     * projection's `ownership` is the one source a key-holder always has. Ownership is
+     * immutable for the life of an agent, so the cache never needs invalidating.
+     */
+    const ownershipByAgent = new Map();
+    const artifactSelectors = async (agentId) => {
+        const hit = ownershipByAgent.get(agentId);
+        if (hit)
+            return hit;
+        const projection = await json(agents(agentId));
+        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');
+        }
+        const sel = { owner_uid: own.owner_uid, org_id: own.org_id };
+        ownershipByAgent.set(agentId, sel);
+        return sel;
+    };
+    const client = {
+        listModels: async () => {
+            const data = await json('/models');
+            return Array.isArray(data) ? data : (data.models ?? []);
+        },
+        createAgent: (input, idempotencyKey) => {
+            // Runtime strip, not just type-level: `warm` races the platform credential seeding
+            // (sandbox born without creds, never heals — zooclaw-engine#791), and the BOOTSTRAP
+            // interview is never what an API caller wants. JS callers bypass the types, so both
+            // are enforced here.
+            const { warm: _warm, onboarding: _onboarding, ...resource } = input.resource;
+            return json('/agents', {
+                method: 'POST',
+                body: JSON.stringify({
+                    resource: { ...resource, onboarding: false },
+                    ...(input.ownership ? { ownership: input.ownership } : {}),
+                }),
+                ...(idempotencyKey ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}),
+            });
+        },
+        listAgents: async (opts = {}) => {
+            const params = { page: opts.page };
+            for (const [k, v] of Object.entries(opts.labels ?? {}))
+                params[`label.${k}`] = v;
+            const data = await json(`/agents${query(params)}`);
+            return data.agents ?? [];
+        },
+        getAgent: (agentId) => json(agents(agentId)),
+        updateAgent: (agentId, sections) => json(agents(agentId), { method: 'PUT', body: JSON.stringify(sections) }),
+        deleteAgent: async (agentId) => {
+            await json(agents(agentId), { method: 'DELETE' });
+        },
+        startAgent: async (agentId) => {
+            const data = await json(`${agents(agentId)}/start`, { method: 'POST' });
+            return { warnings: data.warnings ?? [] };
+        },
+        stopAgent: async (agentId) => {
+            const data = await json(`${agents(agentId)}/stop`, { method: 'POST' });
+            return { warnings: data.warnings ?? [] };
+        },
+        waitUntilRunning: async (agentId, opts = {}) => {
+            const timeoutMs = opts.timeoutMs ?? 30_000;
+            const intervalMs = opts.intervalMs ?? 500;
+            const deadline = Date.now() + timeoutMs;
+            let lastSeen = 'unknown';
+            const abortedError = () => new ZooworkError(0, `waitUntilRunning(${agentId}) aborted`, 'aborted');
+            const timeoutError = () => new ZooworkError(408, `agent ${agentId} did not reach status.desired_state=running within ${timeoutMs}ms ` +
+                `(last seen: ${lastSeen})`, 'timeout');
+            for (;;) {
+                if (opts.signal?.aborted)
+                    throw abortedError();
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    throw timeoutError();
+                // THE POLL ITSELF IS BOUNDED, not just the gap between polls. `fetch` has no default
+                // timeout anywhere we run, so a gateway that accepts the connection and then stalls
+                // would otherwise park this promise forever — outliving both `timeoutMs` and the
+                // caller's `signal`, which is the exact never-returning readiness loop this helper
+                // exists to prevent. The per-request signal fires on whichever comes first.
+                const poll = new AbortController();
+                const cancelPoll = () => poll.abort();
+                opts.signal?.addEventListener('abort', cancelPoll, { once: true });
+                const budget = setTimeout(cancelPoll, remaining);
+                let agent;
+                try {
+                    agent = await json(agents(agentId), { signal: poll.signal });
+                }
+                catch (e) {
+                    // Our own cancellation surfaces as a fetch AbortError; translate it into the two
+                    // outcomes this method documents instead of leaking a DOMException.
+                    if (poll.signal.aborted)
+                        throw opts.signal?.aborted ? abortedError() : timeoutError();
+                    throw e;
+                }
+                finally {
+                    clearTimeout(budget);
+                    opts.signal?.removeEventListener('abort', cancelPoll);
+                }
+                // desired_state, never actual_state — see the doc comment on this method.
+                lastSeen = agent.status?.desired_state ?? 'unknown';
+                if (lastSeen === 'running')
+                    return agent;
+                if (Date.now() + intervalMs > deadline)
+                    throw timeoutError();
+                await sleep(intervalMs, opts.signal);
+            }
+        },
+        listAgentSkills: async (agentId, opts = {}) => {
+            const data = await json(`${agents(agentId)}/skills${opts.verbose ? '?verbose=true' : ''}`);
+            return data.skills ?? [];
+        },
+        putAgentSkill: (agentId, skillId, opts = {}) => json(`${agents(agentId)}/skills/${encodeURIComponent(skillId)}`, {
+            method: 'PUT',
+            body: JSON.stringify({ enabled: opts.enabled ?? true, version_pin: opts.versionPin ?? null }),
+        }),
+        deleteAgentSkill: async (agentId, skillId) => {
+            await json(`${agents(agentId)}/skills/${encodeURIComponent(skillId)}`, { method: 'DELETE' });
+        },
+        listChannels: async (agentId) => {
+            const data = await json(`${agents(agentId)}/channels`);
+            return data.channels ?? [];
+        },
+        addChannel: (agentId, input) => json(`${agents(agentId)}/channels`, { method: 'POST', body: JSON.stringify(input) }),
+        updateChannel: (agentId, platform, input = {}) => json(`${agents(agentId)}/channels/${encodeURIComponent(platform)}/update`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        }),
+        removeChannel: async (agentId, platform, opts = {}) => {
+            await json(`${agents(agentId)}/channels/${encodeURIComponent(platform)}/remove`, {
+                method: 'POST',
+                body: JSON.stringify({ account: opts.account ?? 'default' }),
+            });
+        },
+        startFeishuSetup: (agentId, input = {}) => json(`${agents(agentId)}/channels/feishu/setup`, { method: 'POST', body: JSON.stringify(input) }),
+        pollFeishuSetup: (agentId, sessionId) => json(`${agents(agentId)}/channels/feishu/poll${query({ session_id: sessionId })}`),
+        cancelFeishuSetup: async (agentId, sessionId) => {
+            await json(`${agents(agentId)}/channels/feishu/setup/cancel${query({ session_id: sessionId })}`, {
+                method: 'POST',
+            });
+        },
+        waitForFeishuSetup: async (agentId, sessionId, opts = {}) => {
+            const timeoutMs = opts.timeoutMs ?? 600_000;
+            const deadline = Date.now() + timeoutMs;
+            let lastStatus = 'unknown';
+            const abortedError = () => new ZooworkError(0, `waitForFeishuSetup(${agentId}, ${sessionId}) aborted`, 'aborted');
+            const timeoutError = () => new ZooworkError(408, `Feishu setup session ${sessionId} still '${lastStatus}' after ${timeoutMs}ms — ` +
+                'the QR may simply not have been scanned yet; the session itself expires server-side', 'timeout');
+            for (;;) {
+                if (opts.signal?.aborted)
+                    throw abortedError();
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    throw timeoutError();
+                // Same in-flight bound as waitUntilRunning: without it, a stalled gateway would park
+                // this promise past both the budget and the caller's signal.
+                const poll = new AbortController();
+                const cancelPoll = () => poll.abort();
+                opts.signal?.addEventListener('abort', cancelPoll, { once: true });
+                const budget = setTimeout(cancelPoll, remaining);
+                let result;
+                try {
+                    result = await json(`${agents(agentId)}/channels/feishu/poll${query({ session_id: sessionId })}`, { signal: poll.signal });
+                }
+                catch (e) {
+                    if (poll.signal.aborted)
+                        throw opts.signal?.aborted ? abortedError() : timeoutError();
+                    throw e;
+                }
+                finally {
+                    clearTimeout(budget);
+                    opts.signal?.removeEventListener('abort', cancelPoll);
+                }
+                opts.onPoll?.(result);
+                lastStatus = result.status ?? 'unknown';
+                // Only a literal 'pending' keeps the loop alive… except that an UNKNOWN status is
+                // treated as still-in-flight too (see FeishuPollResult): a new intermediate state on
+                // the server should stretch the wait, not end it with a fake terminal result.
+                const terminal = ['success', 'expired', 'denied', 'error'].includes(lastStatus);
+                if (terminal)
+                    return result;
+                // Server semantics: poll_interval is in SECONDS. The floor only guards a 0/negative
+                // value from ever busy-looping the gateway.
+                const intervalMs = Math.max(250, (result.poll_interval ?? 5) * 1000);
+                if (Date.now() + intervalMs > deadline)
+                    throw timeoutError();
+                await sleep(intervalMs, opts.signal);
+            }
+        },
+        uploadSkill: (zip, opts) => {
+            const form = skillForm(zip, opts);
+            form.append('scope', opts.scope);
+            return multipart('/skills', form, {
+                ...(opts.idempotencyKey ? { headers: { 'Idempotency-Key': opts.idempotencyKey } } : {}),
+            });
+        },
+        uploadSkillVersion: (skillId, zip, opts = {}) => multipart(`/skills/${encodeURIComponent(skillId)}/versions`, skillForm(zip, opts), {
+            ...(opts.idempotencyKey ? { headers: { 'Idempotency-Key': opts.idempotencyKey } } : {}),
+        }),
+        listSkills: async (opts = {}) => {
+            const data = await json(`/skills${query({ scope: opts.scope, q: opts.q, page: opts.page })}`);
+            return data.skills ?? [];
+        },
+        deleteSkill: async (skillId) => {
+            await json(`/skills/${encodeURIComponent(skillId)}`, { method: 'DELETE' });
+        },
+        createSession: (agentId, input, idempotencyKey) => json(sessions(agentId), {
+            method: 'POST',
+            body: JSON.stringify(input),
+            ...(idempotencyKey ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}),
+        }),
+        getSession: (agentId, sessionId, opts = {}) => {
+            const q = new URLSearchParams();
+            if (opts.history)
+                q.set('history', 'true');
+            if (opts.limit !== undefined)
+                q.set('limit', String(opts.limit));
+            const qs = q.toString();
+            return json(`${sessions(agentId)}/${encodeURIComponent(sessionId)}${qs ? `?${qs}` : ''}`);
+        },
+        listSessions: async (agentId, opts = {}) => {
+            const data = await json(`${sessions(agentId)}${query({ page: opts.page })}`);
+            return data.sessions ?? [];
+        },
+        archiveSession: async (agentId, sessionId) => {
+            const data = await json(`${sessions(agentId)}/${encodeURIComponent(sessionId)}/archive`, { method: 'POST' });
+            return { ...data, archived: data.archived ?? false };
+        },
+        deleteSession: async (agentId, sessionId) => {
+            await json(`${sessions(agentId)}/${encodeURIComponent(sessionId)}`, { method: 'DELETE' });
+        },
+        postEvents: async (agentId, sessionId, events) => {
+            const data = await json(`${sessions(agentId)}/${encodeURIComponent(sessionId)}/events`, { method: 'POST', body: JSON.stringify({ events }) });
+            return { events: data.events ?? [] };
+        },
+        listEvents: async (agentId, sessionId, opts = {}) => (await client.listEventsPage(agentId, sessionId, opts)).events,
+        listEventsPage: async (agentId, sessionId, opts = {}) => {
+            const data = await json(`${sessions(agentId)}/${encodeURIComponent(sessionId)}/events${query({
+                after: opts.after,
+                cursor: opts.cursor,
+                types: opts.types?.join(','),
+                limit: opts.limit,
+            })}`);
+            return {
+                events: (data.events ?? []).map((e) => normalizeEvent(e)),
+                ...(data.has_more !== undefined ? { hasMore: data.has_more } : {}),
+                ...(data.next_cursor !== undefined ? { nextCursor: data.next_cursor } : {}),
+            };
+        },
+        listAllEvents: async (agentId, sessionId, opts = {}) => {
+            const pageSize = Math.min(Math.max(opts.pageSize ?? 500, 1), 500);
+            const out = [];
+            // Unified lane (default): follow the server's cursor until has_more is false.
+            if (opts.after === undefined) {
+                let pageCursor;
+                for (;;) {
+                    const page = await client.listEventsPage(agentId, sessionId, {
+                        ...(pageCursor !== undefined ? { cursor: pageCursor } : {}),
+                        ...(opts.types ? { types: opts.types } : {}),
+                        limit: pageSize,
+                    });
+                    // A cursor that fails to advance means the same page again — stop before
+                    // re-appending it rather than refetching it forever.
+                    if (page.hasMore !== undefined && page.nextCursor === pageCursor)
+                        return out;
+                    out.push(...page.events);
+                    if (page.hasMore === undefined) {
+                        // Before the first cursor this is a server without cursor pagination: a short
+                        // page already ends the history, a full one continues on the `after` walk below.
+                        // Mid-walk it is a protocol violation — return what we have rather than silently
+                        // switching to the engine-only lane and dropping input events.
+                        if (pageCursor !== undefined || page.events.length < pageSize)
+                            return out;
+                        break;
+                    }
+                    if (!page.hasMore || !page.nextCursor || page.events.length === 0)
+                        return out;
+                    pageCursor = page.nextCursor;
+                }
+            }
+            let cursor = opts.after ?? out.reduce((max, e) => (e.seq > max ? e.seq : max), 0);
+            for (;;) {
+                const page = await client.listEvents(agentId, sessionId, {
+                    after: cursor,
+                    ...(opts.types ? { types: opts.types } : {}),
+                    limit: pageSize,
+                });
+                // Anything at or below the cursor is a boundary replay — or a server that ignored
+                // `after`. Dropping it keeps the result deduplicated AND the walk finite.
+                const fresh = cursor > 0 ? page.filter((e) => e.seq > cursor) : page;
+                out.push(...fresh);
+                const highest = fresh.reduce((max, e) => (e.seq > max ? e.seq : max), cursor);
+                if (page.length < pageSize || highest <= cursor)
+                    return out;
+                cursor = highest;
+            }
+        },
+        async *streamEvents(agentId, sessionId, opts = {}) {
+            const after = opts.after ?? 0;
+            let lastSeq = after;
+            const qs = query(opts.cursor !== undefined ? { cursor: opts.cursor } : { after: after > 0 ? after : undefined });
+            const path = `${sessions(agentId)}/${encodeURIComponent(sessionId)}/events/stream${qs}`;
+            try {
+                const res = await doFetch(`${base}${path}`, {
+                    headers: { Authorization: `Bearer ${bearer}`, Accept: 'text/event-stream' },
+                    ...(opts.signal ? { signal: opts.signal } : {}),
+                });
+                if (!res.ok)
+                    throw new ZooworkError(res.status, `events stream HTTP ${res.status}`);
+                if (!res.body)
+                    return;
+                for await (const msg of parseSSE(res.body)) {
+                    if (msg.event === 'event_delta')
+                        continue;
+                    if (!isObj(msg.data))
+                        continue;
+                    const ev = normalizeEvent(msg.data, msg.id);
+                    // The server already resumes from `after`; this guards the boundary event being
+                    // replayed when a dropped connection is re-established.
+                    if (ev.seq >= 0 && ev.seq <= lastSeq)
+                        continue;
+                    if (ev.seq > lastSeq)
+                        lastSeq = ev.seq;
+                    yield ev;
+                }
+            }
+            catch (e) {
+                if (opts.signal?.aborted)
+                    return;
+                throw e;
+            }
+        },
+        listApprovals: async (agentId, opts = {}) => {
+            const data = await json(`${agents(agentId)}/approvals${query({ status: opts.status })}`);
+            return data.approvals ?? [];
+        },
+        resolveApproval: (agentId, approvalId, input) => json(`${agents(agentId)}/approvals/${encodeURIComponent(approvalId)}/resolve`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        }),
+        getSystemPrompt: (agentId) => json(`${agents(agentId)}/system-prompt`),
+        // The colon goes RAW here: this family matches the literal `system-prompt:preview` segment,
+        // and both spellings pass the gateway (verified 2026-08-14) — so raw also serves the
+        // deployment-internal direct mode, whose HTTP server never percent-decodes the path.
+        previewSystemPrompt: (agentId, input) => json(`${agents(agentId)}/system-prompt:preview`, { method: 'POST', body: JSON.stringify(input) }),
+        upgradeSystemPrompt: (agentId, input) => json(`${agents(agentId)}:upgrade-system-prompt`, { method: 'POST', body: JSON.stringify(input) }),
+        listArtifacts: async (agentId, opts = {}) => {
+            const sel = await artifactSelectors(agentId);
+            const data = await json(`${agents(agentId)}/artifacts${query({
+                ...sel,
+                page: opts.page,
+                limit: opts.limit,
+                session_id: opts.sessionId,
+                source_path: opts.sourcePath,
+                created_before: opts.createdBefore,
+            })}`);
+            return { ...data, artifacts: data.artifacts ?? [] };
+        },
+        getArtifact: async (agentId, artifactId) => {
+            const sel = await artifactSelectors(agentId);
+            return json(`${agents(agentId)}/artifacts/${encodeURIComponent(artifactId)}${query({ ...sel })}`);
+        },
+        downloadArtifact: async (agentId, artifactId) => {
+            const sel = await artifactSelectors(agentId);
+            return json(`${agents(agentId)}/artifacts/${encodeURIComponent(artifactId)}:download${query({ ...sel })}`, {
+                method: 'POST',
+            });
+        },
+        deleteArtifact: async (agentId, artifactId) => {
+            const sel = await artifactSelectors(agentId);
+            return json(`${agents(agentId)}/artifacts/${encodeURIComponent(artifactId)}${query({ ...sel })}`, {
+                method: 'DELETE',
+            });
+        },
+        listSchedules: async (agentId) => {
+            const data = await json(schedules(agentId));
+            return data.schedules ?? [];
+        },
+        createSchedule: (agentId, input, idempotencyKey) => json(schedules(agentId), {
+            method: 'POST',
+            body: JSON.stringify(input),
+            ...(idempotencyKey ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}),
+        }),
+        getSchedule: (agentId, scheduleId) => json(`${schedules(agentId)}/${encodeURIComponent(scheduleId)}`),
+        updateSchedule: (agentId, scheduleId, update) => {
+            // Stripped rather than forwarded. Every one of these is a field `getSchedule()` hands you
+            // and the PUT refuses: four are `server-derived` 400s, `sessionTarget` is an `immutable`
+            // 400, and `scheduleSpec` is worse than a 400 — it is accepted and ignored, so echoing a
+            // read back would answer 200 while quietly dropping the cadence change. The types already
+            // refuse all six; this is what makes the same round trip work from JavaScript.
+            const { sessionTarget: _immutable, scheduleSpec: _readShape, execution: _derived1, originMetadata: _derived2, contextSnapshot: _derived3, creatorPrincipalRef: _derived4, ...body } = update;
+            return json(`${schedules(agentId)}/${encodeURIComponent(scheduleId)}`, {
+                method: 'PUT',
+                body: JSON.stringify(body),
+            });
+        },
+        deleteSchedule: async (agentId, scheduleId) => {
+            await json(`${schedules(agentId)}/${encodeURIComponent(scheduleId)}`, { method: 'DELETE' });
+        },
+        triggerSchedule: async (agentId, scheduleId) => {
+            const data = await json(`${schedules(agentId)}/${encodeURIComponent(scheduleId)}/trigger`, { method: 'POST' });
+            return { ...data, triggered: data.triggered ?? false };
+        },
+        listScheduleRuns: async (agentId, scheduleId, opts = {}) => {
+            const data = await json(`${schedules(agentId)}/${encodeURIComponent(scheduleId)}/runs${query({ limit: opts.limit })}`);
+            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 }) }),
+        listEnvironments: async (opts = {}) => {
+            const data = await json(`/environments${query({ page: opts.page })}`);
+            return data.environments ?? [];
+        },
+        getEnvironment: (environmentId) => json(environments(environmentId)),
+        createEnvironment: (input, idempotencyKey) => json('/environments', {
+            method: 'POST',
+            body: JSON.stringify(input),
+            ...(idempotencyKey ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}),
+        }),
+        // `%3A`, never a literal ':' — the engine misses the route on a raw colon and answers 404.
+        archiveEnvironment: (environmentId) => json(`/environments/${encodeURIComponent(environmentId)}%3Aarchive`, { method: 'POST' }),
+        createEnvironmentVersion: (environmentId, config, idempotencyKey) => json(`${environments(environmentId)}/versions`, {
+            method: 'POST',
+            body: JSON.stringify({ resource: { config } }),
+            ...(idempotencyKey ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}),
+        }),
+        getEnvironmentVersion: (environmentId, version) => json(`${environments(environmentId)}/versions/${encodeURIComponent(String(version))}`),
+    };
+    return client;
+}