primitive-admin 1.2.0-alpha.1 → 1.2.0-alpha.10

package/dist/src/lib/api-client.js

@@ -1,9 +1,9 @@
 import { loadCredentials, saveCredentials, isTokenExpiringSoon, } from "./config.js";
-import { getCurrentEnvNameSafe } from "./env-resolver.js";
+import { getCurrentEnvNameSafe, getProjectConfig } from "./env-resolver.js";
+import { pinRefusalHint } from "./pin-refusal-hint.js";
 import { fetchWithTLS } from "./fetch.js";
 import { paginateAll, normalizeCliListEnvelope } from "./paginate.js";
 import { RefreshError, refreshAdminCredentials, } from "./refresh-admin-credentials.js";
-import { drainAppsUntilConverged, } from "./workflow-usage.js";
 /**
  * Page size the admin per-user inventories are asked for (#3399).
  *
@@ -11,6 +11,15 @@ import { drainAppsUntilConverged, } from "./workflow-usage.js";
  * fewest round trips the contract allows; a larger value is clamped there.
  */
 const ADMIN_INVENTORY_PAGE_SIZE = 100;
+/** The agent block's wire keys, in the surface's order. */
+const AGENT_TEST_CASE_WIRE_KEYS = [
+    "agentHistory",
+    "agentContext",
+    "agentTimezone",
+    "agentLocale",
+    "agentExpectedToolCall",
+    "agentExpectedNoToolCall",
+];
 export class ApiError extends Error {
     statusCode;
     code;
@@ -39,6 +48,15 @@ export class ApiError extends Error {
         }
     }
 }
+/** The project's committed environments, or null outside a readable project. */
+function projectEnvironments() {
+    try {
+        return getProjectConfig()?.environments ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 export class ConflictError extends ApiError {
     serverModifiedAt;
     expectedModifiedAt;
@@ -85,6 +103,15 @@ export function parseErrorResponse(response, text, path) {
         // Non-JSON body. Surface the existing `<!DOCTYPE` special-case (an HTML
         // 404 page from hitting the wrong path) so we don't regress the helpful
         // "API endpoint not found" message at api-client.ts:343.
+        //
+        // An HTML page with any other status is not a wrong path: it keeps its
+        // status, so a gateway's 502 is retried and a 403 is not read as absence
+        // (#4148).
+        if (text.includes("<!DOCTYPE") && response.status !== 404) {
+            return {
+                message: `HTTP ${response.status}: the server answered with an HTML error page`,
+            };
+        }
         if (text.includes("<!DOCTYPE")) {
             const where = path ? `: ${path}` : "";
             return {
@@ -116,55 +143,15 @@ export function parseErrorResponse(response, text, path) {
     return { message, code, details, raw: errorData };
 }
 /**
- * Typed exception classes for the database-schema feature (issue #666).
- * Each maps 1:1 to a server `code` value emitted from the op-edit or
- * schema-edit gate. They all extend ApiError so existing catch-all paths
- * continue to work; specialized catch blocks can branch on `instanceof`.
- *
- * Per round-2 addendum A1, `details` is always preserved so callers can
- * extract structured offender lists (refs[], operations[], etc.).
+ * Typed exception for the database-schema feature (issue #666): a stored
+ * schema that does not parse. `details` carries the line and column.
+ * (#3189 — the operation gates' exceptions retired with operations.)
  */
-export class SchemaRequiredError extends ApiError {
-    constructor(message, details) {
-        super(message, 422, "SCHEMA_REQUIRED", details);
-        this.name = "SchemaRequiredError";
-    }
-}
 function detailsRecord(details) {
     return details && !Array.isArray(details) && typeof details === "object"
         ? details
         : undefined;
 }
-export class OperationRefError extends ApiError {
-    constructor(message, details) {
-        super(message, 422, "OPERATION_REFERENCES_UNDEFINED", details);
-        this.name = "OperationRefError";
-    }
-    get refs() {
-        const d = detailsRecord(this.details);
-        return Array.isArray(d?.refs) ? d.refs : [];
-    }
-}
-export class SchemaBreaksOpsError extends ApiError {
-    constructor(message, details) {
-        super(message, 422, "SCHEMA_BREAKS_OPERATIONS", details);
-        this.name = "SchemaBreaksOpsError";
-    }
-    get operations() {
-        const d = detailsRecord(this.details);
-        return Array.isArray(d?.operations) ? d.operations : [];
-    }
-}
-export class SchemaHasUncheckableOpsError extends ApiError {
-    constructor(message, details) {
-        super(message, 422, "SCHEMA_HAS_UNCHECKABLE_OPS", details);
-        this.name = "SchemaHasUncheckableOpsError";
-    }
-    get operations() {
-        const d = detailsRecord(this.details);
-        return Array.isArray(d?.operations) ? d.operations : [];
-    }
-}
 export class TomlParseError extends ApiError {
     constructor(message, details) {
         super(message, 400, "TOML_PARSE_ERROR", details);
@@ -179,55 +166,6 @@ export class TomlParseError extends ApiError {
         return typeof d?.column === "number" ? d.column : undefined;
     }
 }
-export class OpsExistError extends ApiError {
-    constructor(message, details) {
-        super(message, 409, "OPS_EXIST", details);
-        this.name = "OpsExistError";
-    }
-    get opCount() {
-        const d = detailsRecord(this.details);
-        return typeof d?.opCount === "number" ? d.opCount : 0;
-    }
-}
-/**
- * Normalize a `databases operations execute` result to the CLI's one list
- * envelope — but only when the result is a Durable Object query page
- * (issue #2440).
- *
- * A registered operation is a list only sometimes. Of the shapes the server's
- * operation dispatch can return, exactly two carry a top-level `data` array: a
- * bare `query` and a `pipeline` whose `returnField` names a query step. A
- * `count` (`{ count }`), an `aggregate` (`{ result }`), a mutation
- * (`{ results }`), an `applyToQuery` (`{ matched, affected, failed, … }`) and a
- * `returnField: "all"` pipeline (`{ steps: { … } }`) do not, so blanket
- * normalization would corrupt them. This helper therefore tests the shape
- * first and passes everything else through byte-for-byte — including the
- * nested steps of a `returnField: "all"` pipeline, which are operation-defined
- * objects the CLI must not reach into.
- *
- * Deliberately narrow, not a general-purpose predicate: the contract is
- * specifically "an operations-execute result may be a DO query page".
- * `executeDatabaseOperation()` is the only caller.
- *
- * The conversion itself is delegated to `normalizeCliListEnvelope()` so cursor
- * handling, `prevCursor` dropping and `hasMore` derivation have exactly one
- * implementation. That helper throws on an unrecognized shape — correct when
- * the payload is supposed to be a list, wrong here, where the payload is the
- * caller's own result — which is why the shape test has to run first. `_timing`
- * (`--timing`) is re-attached afterwards, since it rides alongside the envelope
- * rather than inside it.
- */
-export function normalizeDatabaseOperationResult(raw) {
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
-        return raw;
-    const page = raw;
-    if (!Array.isArray(page.data))
-        return raw;
-    const envelope = normalizeCliListEnvelope(page);
-    if (page._timing !== undefined)
-        envelope._timing = page._timing;
-    return envelope;
-}
 export class ApiClient {
     /**
      * Loaded on first use (`ensureAuthenticated`), never in a constructor.
@@ -284,8 +222,9 @@ export class ApiClient {
                 // error or a server-side rejection. Callers that need a finer
                 // distinction (e.g. `primitive token`) consume RefreshError directly
                 // from refresh-admin-credentials.ts instead of going through here.
-                // A revoked session (#3885) says so.
-                throw new ApiError(err.code === "SESSION_REVOKED"
+                // A refusal naming the session says why: revoked (#3885), or a login
+                // made before scoped sessions (#3891).
+                throw new ApiError(err.code === "SESSION_REVOKED" || err.code === "SESSION_UNSCOPED"
                     ? err.message
                     : "Token refresh failed. Please login again.", 401, err.code);
             }
@@ -295,60 +234,133 @@ export class ApiClient {
     async request(path, options = {}) {
         const credentials = await this.ensureAuthenticated();
         const url = `${credentials.serverUrl}${path}`;
-        const headers = {
-            Authorization: `Bearer ${credentials.accessToken}`,
-            "Content-Type": "application/json",
-            ...(options.headers || {}),
-        };
-        // Include globalAdminAppId if available (required for admin API calls)
-        if (credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
-        const response = await fetchWithTLS(url, {
-            ...options,
-            headers,
-        });
-        const text = await response.text();
-        if (!response.ok) {
-            const parsed = parseErrorResponse(response, text, path);
-            // Preserve the `<!DOCTYPE` → 404 ApiError shape (status forced to 404).
-            if (parsed.htmlNotFound) {
-                throw new ApiError(parsed.message, 404);
-            }
-            // Narrow details to the record shape for the issue #666 typed-exception
-            // dispatch below. Conflict metadata may live under `details.*` (canonical
-            // location per A1) or on the top-level envelope (legacy).
-            const detailsRecord = parsed.details && !Array.isArray(parsed.details)
-                ? parsed.details
-                : undefined;
-            const serverModifiedAt = detailsRecord?.serverModifiedAt ?? parsed.raw?.serverModifiedAt;
-            const expectedModifiedAt = detailsRecord?.expectedModifiedAt ?? parsed.raw?.expectedModifiedAt;
-            // Typed exceptions for the schema-feature (issue #666).
-            if (response.status === 409 && parsed.code === "CONFLICT") {
-                throw new ConflictError(parsed.message, serverModifiedAt, expectedModifiedAt, detailsRecord);
-            }
-            if (response.status === 409 && parsed.code === "OPS_EXIST") {
-                throw new OpsExistError(parsed.message, detailsRecord);
-            }
-            if (response.status === 400 && parsed.code === "TOML_PARSE_ERROR") {
-                throw new TomlParseError(parsed.message, detailsRecord);
-            }
-            if (response.status === 422 && parsed.code === "SCHEMA_REQUIRED") {
-                throw new SchemaRequiredError(parsed.message, detailsRecord);
+        const send = async (accessToken) => {
+            const headers = {
+                Authorization: `Bearer ${accessToken}`,
+                "Content-Type": "application/json",
+                ...(options.headers || {}),
+            };
+            // Include globalAdminAppId if available (required for admin API calls)
+            if (credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
             }
-            if (response.status === 422 && parsed.code === "OPERATION_REFERENCES_UNDEFINED") {
-                throw new OperationRefError(parsed.message, detailsRecord);
+            const response = await fetchWithTLS(url, {
+                ...options,
+                headers,
+            });
+            return { response, text: await response.text() };
+        };
+        let { response, text } = await send(credentials.accessToken);
+        // #3889 — a 403 naming `admin` is retried once with a stored, unexpired
+        // step-up, and (#4564) so is a write a protected app refused for want of
+        // one. A retry refused 401 means the step-up is gone (revoked or expired
+        // early): drop it and show the original refusal. The retry's own refusal
+        // (say, a step-up without the scope this command needs) is shown as it is.
+        if (response.status === 403 && this.stepUpApplies(response, text, path)) {
+            const retried = await send(credentials.stepUp.accessToken);
+            if (retried.response.ok) {
+                return retried.text ? JSON.parse(retried.text) : null;
             }
-            if (response.status === 422 && parsed.code === "SCHEMA_BREAKS_OPERATIONS") {
-                throw new SchemaBreaksOpsError(parsed.message, detailsRecord);
+            if (retried.response.status === 401) {
+                this.dropStepUp();
             }
-            if (response.status === 422 && parsed.code === "SCHEMA_HAS_UNCHECKABLE_OPS") {
-                throw new SchemaHasUncheckableOpsError(parsed.message, detailsRecord);
+            else {
+                ({ response, text } = retried);
             }
-            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
+        }
+        if (!response.ok) {
+            throw this.responseError(response, text, path);
         }
         return text ? JSON.parse(text) : null;
     }
+    /**
+     * Whether a 403 should be retried with the stored step-up: it names
+     * `admin` among the missing scopes, or it is a protected app's refusal of
+     * a token that is no step-up, and an unexpired step-up is stored.
+     */
+    stepUpApplies(response, text, path) {
+        const stepUp = this.credentials?.stepUp;
+        if (!stepUp?.accessToken)
+            return false;
+        if (new Date(stepUp.expiresAt).getTime() <= Date.now())
+            return false;
+        const parsed = parseErrorResponse(response, text, path);
+        if (parsed.code === "PROTECTED_APP_STEP_UP_REQUIRED")
+            return true;
+        const details = parsed.details;
+        const missing = details && !Array.isArray(details) ? details.missing : undefined;
+        return Array.isArray(missing) && missing.includes("admin");
+    }
+    /**
+     * #4564 — a request outside `request` (an upload, a function invocation)
+     * sent with the CLI's own credentials, retried once with the stored step-up
+     * exactly as `request` retries. `init` builds the request for a bearer. The
+     * answer is the retry's, unless the retry was refused 401: the step-up is
+     * dropped and the original refusal comes back, still readable.
+     */
+    async fetchWithStepUp(url, path, accessToken, init) {
+        const response = await fetchWithTLS(url, init(accessToken));
+        if (response.status !== 403)
+            return response;
+        // Read once to decide; hand the caller a response it can still read.
+        const text = await response.text();
+        const original = new Response(text, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+        if (!this.stepUpApplies(response, text, path))
+            return original;
+        const retried = await fetchWithTLS(url, init(this.credentials.stepUp.accessToken));
+        if (retried.status === 401) {
+            await retried.text().catch(() => "");
+            this.dropStepUp();
+            return original;
+        }
+        return retried;
+    }
+    /** Forget a step-up the server no longer accepts. */
+    dropStepUp() {
+        if (!this.credentials?.stepUp)
+            return;
+        const { stepUp: _dropped, ...rest } = this.credentials;
+        this.credentials = rest;
+        saveCredentials(rest);
+    }
+    /** The typed error a failed response throws. */
+    responseError(response, text, path) {
+        const parsed = parseErrorResponse(response, text, path);
+        // Preserve the `<!DOCTYPE` → 404 ApiError shape.
+        if (parsed.htmlNotFound) {
+            return new ApiError(parsed.message, 404);
+        }
+        // Narrow details to the record shape for the issue #666 typed-exception
+        // dispatch below. Conflict metadata may live under `details.*` (canonical
+        // location per A1) or on the top-level envelope (legacy).
+        const detailsRecord = parsed.details && !Array.isArray(parsed.details)
+            ? parsed.details
+            : undefined;
+        const serverModifiedAt = detailsRecord?.serverModifiedAt ?? parsed.raw?.serverModifiedAt;
+        const expectedModifiedAt = detailsRecord?.expectedModifiedAt ?? parsed.raw?.expectedModifiedAt;
+        // Typed exceptions for the schema-feature (issue #666).
+        if (response.status === 409 && parsed.code === "CONFLICT") {
+            return new ConflictError(parsed.message, serverModifiedAt, expectedModifiedAt, detailsRecord);
+        }
+        if (response.status === 400 && parsed.code === "TOML_PARSE_ERROR") {
+            return new TomlParseError(parsed.message, detailsRecord);
+        }
+        // #4512 — a pin refusal on another environment's app names its login.
+        const hint = pinRefusalHint(parsed, this.credentials?.serverUrl ?? "", projectEnvironments());
+        return new ApiError(hint ? `${parsed.message} ${hint}` : parsed.message, response.status, parsed.code, parsed.details);
+    }
+    /**
+     * `POST /admin/api/auth/token` — derive a token no wider than the stored
+     * one (`primitive token --scope`, #3889). A wider request is refused with
+     * `TOKEN_WIDER_THAN_PRESENTED`.
+     */
+    async exchangeToken(body) {
+        return this.post("/admin/api/auth/token", body);
+    }
     // Helper for GET requests with query params
     async get(path, params) {
         let fullPath = path;
@@ -410,6 +422,10 @@ export class ApiClient {
             qs.set("limit", String(params.limit));
         if (params?.cursor)
             qs.set("cursor", params.cursor);
+        // `kind` filters by lineage: `parent` is apps with no parent, `child`
+        // child apps. Omitted lists every app the caller is assigned to.
+        if (params?.kind)
+            qs.set("kind", params.kind);
         const q = qs.toString();
         const resp = await this.get(`/admin/api/admins/me/apps${q ? `?${q}` : ""}`);
         return {
@@ -432,40 +448,53 @@ export class ApiClient {
         return { apps };
     }
     /**
-     * Every app on the server, not just the caller's own.
-     *
-     * Deliberately separate from `listApps()`, whose contract is "apps assigned
-     * to me" (`GET /admin/api/admins/me/apps`, backed by `admin.queryApps()`) —
-     * the contract every other command depends on. `analytics workflow-usage
-     * --all-apps` has to reach apps nobody is assigned to, which is the global
-     * route `GET /admin/api/apps` (`App.iterateAll()`), and that route
-     * identifies an app as `appId` rather than `id` (D3130-001).
-     *
-     * One drain of that route is lossy — its cursor re-scans `App.iterateAll()`
-     * from the start of each page, so a list that changes under it both repeats
-     * and drops rows — so the walk is the union of repeated drains
-     * (`drainAppsUntilConverged`, which carries the measurement).
-     */
-    async listAllAppsGlobal() {
-        const drainOnce = () => paginateAll(async (cursor) => {
-            const qs = new URLSearchParams({ limit: "100" });
-            if (cursor)
-                qs.set("cursor", cursor);
-            const resp = await this.get(`/admin/api/apps?${qs.toString()}`);
-            const rows = resp.items ?? [];
-            return {
-                items: rows.map((row) => ({
-                    appId: String(row.appId ?? row.id ?? ""),
-                    name: String(row.name ?? ""),
-                })),
-                nextCursor: resp.nextCursor,
-            };
-        });
-        return drainAppsUntilConverged(drainOnce);
-    }
+     * Create an app. An ordinary app takes `name` (and, for a super-admin,
+     * `initialAdminEmail`). A child app takes `parentAppId` and `childSlug`
+     * instead, plus the optional `branch`, `idleDays` (7-30, default 30) and
+     * `copySecrets` (default true); the server names it `<parent name> /
+     * <slug>` and copies the parent's settings.
+     */
     async createApp(data) {
         return this.post("/admin/api/apps", data);
     }
+    /**
+     * One page of an app's child apps, in creation order
+     * (`GET /admin/api/apps/{appId}/children`).
+     */
+    async listAppChildren(parentAppId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit !== undefined)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        const resp = await this.get(`/admin/api/apps/${encodeURIComponent(parentAppId)}/children${q ? `?${q}` : ""}`);
+        return {
+            items: resp?.items ?? [],
+            hasMore: resp?.hasMore ?? false,
+            nextCursor: resp?.nextCursor ?? null,
+        };
+    }
+    /**
+     * Add one origin to a child's preview origins
+     * (`POST /admin/api/apps/{parentAppId}/children/{slug}/preview-origins`).
+     */
+    async addChildPreviewOrigin(parentAppId, slug, origin) {
+        return this.post(this.childPreviewOriginsPath(parentAppId, slug), { origin });
+    }
+    /**
+     * Remove one origin from a child's preview origins
+     * (`DELETE /admin/api/apps/{parentAppId}/children/{slug}/preview-origins`).
+     */
+    async removeChildPreviewOrigin(parentAppId, slug, origin) {
+        return this.request(this.childPreviewOriginsPath(parentAppId, slug), {
+            method: "DELETE",
+            body: JSON.stringify({ origin }),
+        });
+    }
+    childPreviewOriginsPath(parentAppId, slug) {
+        return `/admin/api/apps/${encodeURIComponent(parentAppId)}/children/${encodeURIComponent(slug)}/preview-origins`;
+    }
     async getApp(appId) {
         return this.get(`/admin/api/apps/${appId}`);
     }
@@ -487,6 +516,14 @@ export class ApiClient {
     async addUserByEmail(appId, data) {
         return this.post(`/admin/api/apps/${appId}/users/add-by-email`, data);
     }
+    /**
+     * Set a member's display name and/or avatar URL
+     * (`PATCH /admin/api/apps/:appId/users/:userId/profile`). An omitted field
+     * is left alone; `avatarUrl: null` or `""` clears the avatar.
+     */
+    async setUserProfile(appId, userId, data) {
+        return this.patch(`/admin/api/apps/${appId}/users/${userId}/profile`, data);
+    }
     async mintTestJwt(appId, userId, role) {
         return this.post(`/admin/api/apps/${appId}/users/${userId}/mint-test-jwt`, role ? { role } : {});
     }
@@ -646,7 +683,7 @@ export class ApiClient {
             nextCursor: result?.nextCursor ?? null,
         };
     }
-    /** Integration detail (#2631: `accessRule` is on the detail, not the list summary). */
+    /** Integration detail (`requestConfig` is on the detail, not the list summary). */
     async getIntegration(appId, integrationId) {
         return this.get(`/admin/api/apps/${appId}/integrations/${integrationId}`);
     }
@@ -686,10 +723,6 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/integrations/${integrationId}/logs`, params);
         return result?.items ?? [];
     }
-    async listWorkflowRunIntegrationLogs(appId, runId, params) {
-        const result = await this.get(`/admin/api/apps/${appId}/workflows/runs/${runId}/integration-logs`, params);
-        return result?.items ?? [];
-    }
     // ============================================
     // APP SECRETS
     // ============================================
@@ -749,42 +782,6 @@ export class ApiClient {
     // ============================================
     // WEBHOOKS
     // ============================================
-    async listWebhooks(appId, params) {
-        const result = await this.get(`/admin/api/apps/${appId}/webhooks`, params);
-        return {
-            items: result?.items ?? [],
-            hasMore: result?.hasMore,
-            nextCursor: result?.nextCursor ?? null,
-        };
-    }
-    async getWebhook(appId, webhookId) {
-        return this.get(`/admin/api/apps/${appId}/webhooks/${webhookId}`);
-    }
-    async createWebhook(appId, payload) {
-        return this.post(`/admin/api/apps/${appId}/webhooks`, payload);
-    }
-    async updateWebhook(appId, webhookId, payload, expectedModifiedAt) {
-        const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
-        return this.patch(`/admin/api/apps/${appId}/webhooks/${webhookId}`, body);
-    }
-    /**
-     * Delete a webhook. Archives it by default; `hard` hard-deletes the row
-     * instead (#2232), which is what frees a slot under the per-app webhook cap
-     * and releases the webhook key for reuse. Same `?hard=true` verb the admin
-     * integrations delete uses.
-     */
-    async deleteWebhook(appId, webhookId, options) {
-        const query = options?.hard ? "?hard=true" : "";
-        return this.delete(`/admin/api/apps/${appId}/webhooks/${webhookId}${query}`);
-    }
-    /**
-     * #2803 — the operational verb pair for a webhook. It posts to the
-     * enable/disable route rather than PATCHing `status`, which is server-owned
-     * and refused on every configuration write path.
-     */
-    async setWebhookAvailability(appId, webhookId, action) {
-        return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/${action}`, {});
-    }
     // ── Server functions (#3179) ─────────────────────────────────────────
     //
     // The `functions` family mirrors workflows and scripts: a header with the
@@ -829,6 +826,38 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs`, params);
         return { items: result?.items ?? [], nextCursor: result?.nextCursor ?? null };
     }
+    // ── A function's trigger operations (#3190) ──
+    // The operational home of a function's webhook and cron triggers, keyed by
+    // the function and a cron entry's name rather than a trigger row's id.
+    functionTriggersPath(appId, functionId) {
+        return `/admin/api/apps/${appId}/functions/${encodeURIComponent(functionId)}/triggers`;
+    }
+    /** The function's webhook delivery log, newest first. */
+    async listFunctionWebhookEvents(appId, functionId, params) {
+        const result = await this.get(`${this.functionTriggersPath(appId, functionId)}/webhook/events`, params);
+        const nextCursor = result?.nextCursor ?? null;
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore ?? !!nextCursor,
+            nextCursor,
+        };
+    }
+    /** Sign a preview delivery for the function's webhook trigger. */
+    async testFunctionWebhook(appId, functionId, payload) {
+        return this.post(`${this.functionTriggersPath(appId, functionId)}/webhook/test`, payload || {});
+    }
+    /** Check captured headers and a captured body against the trigger's verifier. */
+    async verifyFunctionWebhook(appId, functionId, payload) {
+        return this.post(`${this.functionTriggersPath(appId, functionId)}/webhook/verify`, payload);
+    }
+    /** Point the trigger's `signingSecret` at a new `{{secrets.KEY}}` reference. */
+    async rotateFunctionWebhookSecret(appId, functionId, payload) {
+        return this.post(`${this.functionTriggersPath(appId, functionId)}/webhook/rotate-secret`, payload);
+    }
+    /** One cron entry verb: `fire`, `fire-scheduled`, `enable` or `disable`. */
+    async functionCronEntryAction(appId, functionId, name, action) {
+        return this.post(`${this.functionTriggersPath(appId, functionId)}/cron/${encodeURIComponent(name)}/${action}`, {});
+    }
     /**
      * A function run's step trace — #3348.
      *
@@ -842,6 +871,16 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}/steps`);
         return { items: result?.items ?? [] };
     }
+    /**
+     * The integration calls one function run made — #3190.
+     *
+     * The run → integration-logs pivot, addressed by the function that owns the
+     * run (it was `workflows/runs/{runId}/integration-logs`).
+     */
+    async listFunctionRunIntegrationLogs(appId, functionId, runId, options) {
+        const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}/integration-logs`, options?.limit !== undefined ? { limit: options.limit } : undefined);
+        return { items: result?.items ?? [] };
+    }
     /**
      * End a function run that will not settle — #3348.
      *
@@ -914,26 +953,31 @@ export class ApiClient {
     async invokeFunction(appId, functionKey, body, options) {
         const credentials = await this.ensureAuthenticated();
         const base = `/app/${appId}/api/functions/${encodeURIComponent(functionKey)}`;
+        const task = options?.runtime === "task";
         const path = options?.asSystem
-            ? `${base}/invoke-as-system`
-            : options?.runtime === "task"
+            ? `${base}/${task ? "start-as-system" : "invoke-as-system"}`
+            : task
                 ? `${base}/start`
                 : base;
-        const headers = {
-            Authorization: `Bearer ${options?.bearer ?? credentials.accessToken}`,
-            "Content-Type": "application/json",
+        const init = (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+                "Content-Type": "application/json",
+            };
+            // The CLI's own credentials reach an app-scoped route through the
+            // global-admin header; a minted user token does not need it and must
+            // not carry it.
+            if (!options?.bearer && credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+            }
+            return { method: "POST", headers, body: JSON.stringify(body) };
         };
-        // The CLI's own credentials reach an app-scoped route through the
-        // global-admin header; a minted user token does not need it and must not
-        // carry it.
-        if (!options?.bearer && credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
-        const response = await fetchWithTLS(`${credentials.serverUrl}${path}`, {
-            method: "POST",
-            headers,
-            body: JSON.stringify(body),
-        });
+        const url = `${credentials.serverUrl}${path}`;
+        // A minted user token is sent as it is; the CLI's own credentials get the
+        // step-up retry a protected app's refusal asks for (#4564).
+        const response = options?.bearer
+            ? await fetchWithTLS(url, init(options.bearer))
+            : await this.fetchWithStepUp(url, path, credentials.accessToken, init);
         const text = await response.text();
         let parsed = null;
         try {
@@ -952,6 +996,38 @@ export class ApiClient {
             body: parsed,
         };
     }
+    /**
+     * Run only a function's `authorize` and hand back the ANSWER, whatever its
+     * HTTP status — #4732. Like `invokeFunction`, it returns a refusal rather
+     * than throwing it, so `functions authorize` renders the server's own
+     * answer (and a case run records it as a failed row); it throws only when
+     * the request did not complete. The CLI's own credentials, with the
+     * step-up retry a protected app's refusal asks for.
+     */
+    async authorizeFunction(appId, functionId, body) {
+        const credentials = await this.ensureAuthenticated();
+        const path = `/admin/api/apps/${appId}/functions/${encodeURIComponent(functionId)}/authorize`;
+        const init = (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+                "Content-Type": "application/json",
+            };
+            if (credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+            }
+            return { method: "POST", headers, body: JSON.stringify(body) };
+        };
+        const response = await this.fetchWithStepUp(`${credentials.serverUrl}${path}`, path, credentials.accessToken, init);
+        const text = await response.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = { error: text };
+        }
+        return { httpStatus: response.status, body: parsed };
+    }
     /**
      * A function's versions, newest first (#3462).
      *
@@ -1004,27 +1080,14 @@ export class ApiClient {
     async setIntegrationAvailability(appId, integrationId, action) {
         return this.post(`/admin/api/apps/${appId}/integrations/${integrationId}/${action}`, {});
     }
-    async rotateWebhookSecret(appId, webhookId, payload) {
-        return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/rotate-secret`, payload);
-    }
-    async listWebhookEvents(appId, webhookId, params) {
-        const result = await this.get(`/admin/api/apps/${appId}/webhooks/${webhookId}/events`, params);
-        const nextCursor = result?.nextCursor ?? null;
-        return {
-            items: result?.items ?? [],
-            hasMore: result?.hasMore ?? !!nextCursor,
-            nextCursor,
-        };
-    }
     // ============================================
     // CONNECTIONS INSPECTION (#1968)
     // ============================================
     /**
      * List the live connections the server believes exist for exactly one of a
-     * document, user, or database. Read-only inspection over admin-api. Rows are
+     * document or user. Read-only inspection over admin-api. Rows are
      * per-connection-×-subscription bindings, so `connectionId` is not unique
-     * across rows. `params` on a database-subscription row is caller-defined
-     * bound CEL input — typed `unknown`.
+     * across rows.
      */
     async listConnections(appId, selector, params) {
         const result = await this.get(`/admin/api/apps/${appId}/connections`, {
@@ -1037,6 +1100,29 @@ export class ApiClient {
             nextCursor: result?.nextCursor ?? null,
         };
     }
+    /**
+     * One page of one user's agent sessions (#3809): the app API's sessions
+     * list, which an app owner or admin may read for any user.
+     */
+    async listAgentSessions(appId, params) {
+        const result = await this.get(`/app/${appId}/api/agent-sessions`, params);
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore,
+            nextCursor: result?.nextCursor ?? null,
+        };
+    }
+    /**
+     * One agent session (#3809): its binding, status, members and active turn,
+     * and for an app owner or admin the session object's state. Never its rows.
+     */
+    async getAgentSession(appId, sessionId) {
+        return this.get(`/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}`);
+    }
+    /** Delete an agent session and its document (#3809); a repeat succeeds again. */
+    async deleteAgentSession(appId, sessionId) {
+        return this.delete(`/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}`);
+    }
     async listSessions(appId, userId, params) {
         const result = await this.get(`/admin/api/apps/${appId}/sessions`, {
             userId,
@@ -1064,20 +1150,6 @@ export class ApiClient {
     async revokeAdminSession(sessionId) {
         return this.delete(`/admin/api/auth/sessions/${encodeURIComponent(sessionId)}`);
     }
-    async testWebhook(appId, webhookId, payload) {
-        return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/test`, payload || {});
-    }
-    /**
-     * Run a webhook's configured verifier over headers and a body captured from
-     * a real delivery, and report whether that signature checks out (#2445).
-     *
-     * `headers` is sent as ordered `[name, value]` pairs so a capture carrying a
-     * field name on more than one line survives the round trip. Nothing is
-     * delivered: no delivery record, no workflow run.
-     */
-    async verifyWebhook(appId, webhookId, payload) {
-        return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/verify`, payload);
-    }
     // ============================================
     // NAMED LOCKS (#1518)
     // ============================================
@@ -1108,51 +1180,6 @@ export class ApiClient {
     // ============================================
     // CRON TRIGGERS
     // ============================================
-    async listCronTriggers(appId) {
-        const result = await this.get(`/app/${appId}/api/cron-triggers`);
-        return { items: result?.items ?? [] };
-    }
-    async getCronTrigger(appId, triggerId) {
-        return this.get(`/app/${appId}/api/cron-triggers/${triggerId}`);
-    }
-    async createCronTrigger(appId, payload) {
-        return this.post(`/app/${appId}/api/cron-triggers`, payload);
-    }
-    async updateCronTrigger(appId, triggerId, payload) {
-        return this.put(`/app/${appId}/api/cron-triggers/${triggerId}`, payload);
-    }
-    /**
-     * Retire a cron trigger. The default soft-deletes (writes the `archived`
-     * tombstone); `{ hard: true }` destroys the row, which is what
-     * `config push --prune` passes (#2803) so a pruned trigger stops consuming
-     * the per-app cap and holding its key.
-     */
-    async deleteCronTrigger(appId, triggerId, options = {}) {
-        const query = options.hard ? "?hard=true" : "";
-        return this.delete(`/app/${appId}/api/cron-triggers/${triggerId}${query}`);
-    }
-    async disableCronTrigger(appId, triggerId) {
-        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/disable`, {});
-    }
-    async enableCronTrigger(appId, triggerId) {
-        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/enable`, {});
-    }
-    async testCronTrigger(appId, triggerId) {
-        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/test`, {});
-    }
-    // ============================================
-    // ITERATIONS (iterate-users introspection / reset — #1209)
-    // ============================================
-    async listIterations(appId) {
-        const result = await this.get(`/app/${appId}/api/iterations`);
-        return { items: result?.items ?? [] };
-    }
-    async getIteration(appId, iterationName) {
-        return this.get(`/app/${appId}/api/iterations/${encodeURIComponent(iterationName)}`);
-    }
-    async resetIteration(appId, iterationName) {
-        return this.post(`/app/${appId}/api/iterations/${encodeURIComponent(iterationName)}/reset`, {});
-    }
     // ============================================
     // RESOURCE METADATA (values — issue #1352)
     // ============================================
@@ -1257,16 +1284,12 @@ export class ApiClient {
         return this.post(`/admin/api/apps/${appId}/prompts/${promptId}/configs/${configId}/duplicate`, payload || {});
     }
     // ============================================
-    // SCRIPTS (Rhai transforms) — #1000 (prompt-model convergence)
+    // SCRIPTS — retained history (#3190)
     // ============================================
     //
-    // The `Script` model is the authoring surface for `script` workflow
-    // steps. A `Script` is a HEADER (name/description/activeConfigId); the
-    // Rhai body lives on versioned `ScriptConfig` rows resolved LIVE at run
-    // time. CLI `config push` reads `transforms/*.rhai` files and reconciles
-    // them: a new file → create script (mints a default config); a changed
-    // file → create a new config + activate it (zero fan-out — referencing
-    // workflows pick up the new body on their next run).
+    // Scripts retired with the Rhai runtime. A `Script` HEADER
+    // (name/description/activeConfigId) and its versioned `ScriptConfig` rows
+    // stay readable until their retention ends; nothing writes them.
     async listScripts(appId) {
         const result = await this.get(`/admin/api/apps/${appId}/scripts`);
         return { items: result?.items ?? [] };
@@ -1279,57 +1302,18 @@ export class ApiClient {
      * is a distinct block version: `configId` is the stable version selector,
      * `contentHash` is its content identity, and `status` reports whether it is
      * `active`/`draft`/`archived`. The script header's `activeConfigId` names
-     * the live version. Used by `scripts configs list` and by the script test
-     * commands to run against a specific pinned version.
+     * the version that was live. Used by `scripts configs list`.
      */
     async listScriptConfigs(appId, scriptId) {
         const result = await this.get(`/admin/api/apps/${appId}/scripts/${scriptId}/configs`);
         return { items: result?.items ?? [] };
     }
-    async createScript(appId, payload) {
-        // Mints the script header + a default `active` config carrying the body.
-        return this.post(`/admin/api/apps/${appId}/scripts`, payload);
-    }
-    /**
-     * Push a new body for an existing script by creating a new `ScriptConfig`
-     * and activating it (the prompt-model "edit → activate" flow). Referencing
-     * workflows pick up the new body on their next run with no fan-out. The
-     * config name is unique per script, so we mint a timestamped name.
-     */
-    async pushScriptBody(appId, scriptId, body, 
-    /**
-     * The active state the caller believes holds right now (#2731 B10).
-     * Creating an inactive config races nothing, so the guard sits on the
-     * ACTIVATION step: if the active config has moved since the caller read it,
-     * the server rejects with a 409 instead of overwriting a concurrent script
-     * change. It takes BOTH halves of "what is active", because a config's body
-     * can be edited in place without the active id changing — the id alone
-     * would let such an edit through. Omitted (e.g. `--force`) means activate
-     * unconditionally.
-     */
-    expectedActive) {
-        const configName = `sync-${Date.now()}`;
-        const config = await this.post(`/admin/api/apps/${appId}/scripts/${scriptId}/configs`, { configName, body });
-        const activateBody = {};
-        if (expectedActive?.configId) {
-            activateBody.expectedActiveConfigId = expectedActive.configId;
-        }
-        if (expectedActive?.modifiedAt) {
-            activateBody.expectedActiveModifiedAt = expectedActive.modifiedAt;
-        }
-        await this.post(`/admin/api/apps/${appId}/scripts/${scriptId}/configs/${config.configId}/activate`, activateBody);
-        return config;
-    }
     /**
-     * Delete a script header (cascades its configs). `force` overrides the
-     * server's guard against deleting a script that an active workflow still
-     * references by name — without it the server answers 409.
+     * One version of a script, body included. A body the server cannot load
+     * answers a 404 naming the version rather than an empty body.
      */
-    async deleteScript(appId, scriptId, force) {
-        const path = force
-            ? `/admin/api/apps/${appId}/scripts/${scriptId}?force=true`
-            : `/admin/api/apps/${appId}/scripts/${scriptId}`;
-        return this.delete(path);
+    async getScriptConfig(appId, scriptId, configId) {
+        return this.get(`/admin/api/apps/${appId}/scripts/${scriptId}/configs/${configId}`);
     }
     async getPromptSchema(appId, promptId) {
         return this.get(`/admin/api/apps/${appId}/prompts/${promptId}/schema`);
@@ -1387,6 +1371,13 @@ export class ApiClient {
         if (payload.expectedJsonSubset) {
             serverPayload.expectedJsonSubset = payload.expectedJsonSubset;
         }
+        // #4262 — an agent case's `[test.agent]` keys, each when the caller set it:
+        // presence, not truthiness, so `agentExpectedNoToolCall: false` travels. A
+        // chat case sets none, and its body is unchanged.
+        for (const key of AGENT_TEST_CASE_WIRE_KEYS) {
+            if (payload[key] !== undefined)
+                serverPayload[key] = payload[key];
+        }
         return this.post(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-cases`, serverPayload);
     }
     async updateTestCase(appId, blockType, blockId, testCaseId, payload) {
@@ -1421,6 +1412,11 @@ export class ApiClient {
         }
         if (payload.key !== undefined)
             serverPayload.key = payload.key;
+        // #4262 — as on create; an explicit `null` clears the field.
+        for (const key of AGENT_TEST_CASE_WIRE_KEYS) {
+            if (payload[key] !== undefined)
+                serverPayload[key] = payload[key];
+        }
         return this.patch(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-cases/${testCaseId}`, serverPayload);
     }
     async deleteTestCase(appId, blockType, blockId, testCaseId) {
@@ -1436,17 +1432,15 @@ export class ApiClient {
         const credentials = await this.ensureAuthenticated();
         const encodedFilename = encodeURIComponent(filename);
         const url = `${credentials.serverUrl}/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-cases/${testCaseId}/attachments/${encodedFilename}`;
-        const headers = {
-            Authorization: `Bearer ${credentials.accessToken}`,
-            "Content-Type": contentType,
-        };
-        if (credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
-        const response = await fetchWithTLS(url, {
-            method: "PUT",
-            headers,
-            body: data,
+        const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+                "Content-Type": contentType,
+            };
+            if (credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+            }
+            return { method: "PUT", headers, body: data };
         });
         const text = await response.text();
         if (!response.ok) {
@@ -1498,7 +1492,7 @@ export class ApiClient {
         return { items: result?.items ?? result ?? [] };
     }
     // ============================================
-    // WORKFLOWS
+    // WORKFLOWS — retained history, read-only (#3190)
     // ============================================
     async listWorkflows(appId, params) {
         const result = await this.get(`/admin/api/apps/${appId}/workflows`, params);
@@ -1511,140 +1505,39 @@ export class ApiClient {
     async getWorkflow(appId, workflowId) {
         return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}`);
     }
-    /**
-     * One app's workflow step usage report (#3132).
-     *
-     * `windowDays` is omitted from the query when the caller did not ask for a
-     * window, so the server applies its own default rather than the CLI
-     * restating it on the wire.
-     */
-    async getWorkflowUsage(appId, params) {
-        return this.get(`/admin/api/apps/${appId}/workflows/usage`, params);
+    // ============================================
+    // WORKFLOW CONFIGURATIONS
+    // ============================================
+    async listWorkflowConfigs(appId, workflowId) {
+        const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/configs`);
+        return { items: result?.items ?? [] };
     }
-    async createWorkflow(appId, payload) {
-        return this.post(`/admin/api/apps/${appId}/workflows`, payload);
+    async getWorkflowConfig(appId, workflowId, configId) {
+        return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}`);
     }
-    async updateWorkflow(appId, workflowId, payload, expectedModifiedAt) {
-        const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
-        return this.patch(`/admin/api/apps/${appId}/workflows/${workflowId}`, body);
+    // ============================================
+    // ANALYTICS
+    // ============================================
+    async getAnalyticsTopUsers(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/users/top`, params);
     }
-    /**
-     * Retire a workflow, or destroy it (#2887).
-     *
-     * The plain call ARCHIVES: the definition row stays, so its runs, revisions
-     * and test cases keep resolving. `{ hard: true }` performs the full cascade
-     * and is what releases the `workflowKey` — the flag `config push --prune`
-     * sends, for the same reason it sends it for webhooks and integrations.
-     */
-    async deleteWorkflow(appId, workflowId, options) {
-        const path = `/admin/api/apps/${appId}/workflows/${workflowId}`;
-        return this.delete(options?.hard ? `${path}?hard=true` : path);
+    async getAnalyticsIntegrationMetrics(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/integrations`, params);
     }
-    /**
-     * #2645 criterion 9 — the operational toggle. Deliberately NOT the config
-     * PATCH: `config push` owns every configuration field, and taking a workflow
-     * out of service must not touch one, or an operator's action would show up as
-     * drift against the repo. Same route shape as `cron-triggers pause|resume`.
-     */
-    async disableWorkflow(appId, workflowId) {
-        return this.post(`/app/${appId}/api/workflows/${workflowId}/disable`, {});
+    async getAnalyticsOverviewDau(appId) {
+        return this.get(`/app/${appId}/api/analytics/overview/dau`);
     }
-    async enableWorkflow(appId, workflowId) {
-        return this.post(`/app/${appId}/api/workflows/${workflowId}/enable`, {});
+    async getAnalyticsOverviewWau(appId) {
+        return this.get(`/app/${appId}/api/analytics/overview/wau`);
     }
-    async updateWorkflowDraft(appId, workflowId, payload) {
-        return this.put(`/admin/api/apps/${appId}/workflows/${workflowId}/draft`, payload);
+    async getAnalyticsOverviewMau(appId) {
+        return this.get(`/app/${appId}/api/analytics/overview/mau`);
     }
-    async previewWorkflow(appId, workflowId, payload) {
-        return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/preview`, payload);
+    async getAnalyticsOverviewGrowth(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/overview/growth`, params);
     }
-    async getPreviewStatus(appId, workflowId, instanceId) {
-        return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/preview/${instanceId}/status`);
-    }
-    async listWorkflowRuns(appId, workflowId, params) {
-        const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs`, params);
-        const nextCursor = result?.nextCursor ?? null;
-        return {
-            items: result?.items ?? [],
-            hasMore: result?.hasMore,
-            nextCursor,
-            resumeAfter: result?.resumeAfter,
-            scanned: typeof result?.scanned === "number" ? result.scanned : undefined,
-        };
-    }
-    /**
-     * Workflow runs started by one app user, across every workflow (#1967).
-     * Backed by `GET /admin/api/apps/{appId}/users/{userId}/workflow-runs`,
-     * which resolves the app user before querying the `runsByUser` index.
-     */
-    async listUserWorkflowRuns(appId, userId, params) {
-        const result = await this.get(`/admin/api/apps/${appId}/users/${encodeURIComponent(userId)}/workflow-runs`, params);
-        const nextCursor = result?.nextCursor ?? null;
-        return {
-            items: result?.items ?? [],
-            hasMore: result?.hasMore,
-            nextCursor,
-            scanned: typeof result?.scanned === "number" ? result.scanned : undefined,
-        };
-    }
-    async getWorkflowRunStatus(appId, workflowId, runId) {
-        return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs/${runId}/status`);
-    }
-    async getWorkflowStepRuns(appId, workflowId, runId) {
-        const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs/${runId}/steps`);
-        return { items: result?.items ?? [] };
-    }
-    // Workflow analytics have one client path, `getAnalyticsTopWorkflows`
-    // (issue #2766): `getTopWorkflows` was a second name for the same endpoint,
-    // and `getWorkflowAnalytics` called a route the server never registered.
-    // ============================================
-    // WORKFLOW CONFIGURATIONS
-    // ============================================
-    async listWorkflowConfigs(appId, workflowId) {
-        const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/configs`);
-        return { items: result?.items ?? [] };
-    }
-    async getWorkflowConfig(appId, workflowId, configId) {
-        return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}`);
-    }
-    async createWorkflowConfig(appId, workflowId, payload) {
-        return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/configs`, payload);
-    }
-    async updateWorkflowConfig(appId, workflowId, configId, payload) {
-        return this.patch(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}`, payload);
-    }
-    async archiveWorkflowConfig(appId, workflowId, configId) {
-        return this.delete(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}`);
-    }
-    async activateWorkflowConfig(appId, workflowId, configId) {
-        return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}/activate`, {});
-    }
-    async duplicateWorkflowConfig(appId, workflowId, configId, payload) {
-        return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}/duplicate`, payload || {});
-    }
-    // ============================================
-    // ANALYTICS
-    // ============================================
-    async getAnalyticsTopUsers(appId, params) {
-        return this.get(`/app/${appId}/api/analytics/users/top`, params);
-    }
-    async getAnalyticsIntegrationMetrics(appId, params) {
-        return this.get(`/app/${appId}/api/analytics/integrations`, params);
-    }
-    async getAnalyticsOverviewDau(appId) {
-        return this.get(`/app/${appId}/api/analytics/overview/dau`);
-    }
-    async getAnalyticsOverviewWau(appId) {
-        return this.get(`/app/${appId}/api/analytics/overview/wau`);
-    }
-    async getAnalyticsOverviewMau(appId) {
-        return this.get(`/app/${appId}/api/analytics/overview/mau`);
-    }
-    async getAnalyticsOverviewGrowth(appId, params) {
-        return this.get(`/app/${appId}/api/analytics/overview/growth`, params);
-    }
-    async getAnalyticsDailyActive(appId, params) {
-        return this.get(`/app/${appId}/api/analytics/daily-active`, params);
+    async getAnalyticsDailyActive(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/daily-active`, params);
     }
     async getAnalyticsRollingActive(appId, params) {
         return this.get(`/app/${appId}/api/analytics/rolling-active`, params);
@@ -1670,9 +1563,6 @@ export class ApiClient {
     async getAnalyticsErrorsGroups(appId, params) {
         return this.get(`/app/${appId}/api/analytics/errors/groups`, params);
     }
-    async getAnalyticsTopWorkflows(appId, params) {
-        return this.get(`/app/${appId}/api/analytics/workflows/top`, params);
-    }
     async getAnalyticsTopPrompts(appId, params) {
         return this.get(`/app/${appId}/api/analytics/prompts/top`, params);
     }
@@ -1984,72 +1874,6 @@ export class ApiClient {
         });
     }
     // ============================================
-    // DATABASE OPERATIONS (registered operations)
-    // ============================================
-    async listDatabaseOperations(appId, databaseId) {
-        return this.get(`/app/${appId}/api/databases/${databaseId}/operations`);
-    }
-    /**
-     * Execute a registered operation and, when the result is a query page,
-     * normalize it to the CLI's one list envelope (issue #2440).
-     *
-     * The registered operation decides the response shape, so the normalization
-     * is conditional — see {@link normalizeDatabaseOperationResult}. Everything
-     * else (a `count`, an `aggregate`, a mutation, a `returnField: "all"`
-     * pipeline) is returned exactly as the server sent it.
-     */
-    async executeDatabaseOperation(appId, databaseId, operationName, data, token, options) {
-        const path = `/app/${appId}/api/databases/${databaseId}/operations/${encodeURIComponent(operationName)}/execute`;
-        const extraHeaders = {};
-        if (options?.timing) {
-            extraHeaders["X-Timing"] = "true";
-        }
-        if (token) {
-            return normalizeDatabaseOperationResult(await this.requestWithToken(path, token, {
-                method: "POST",
-                body: JSON.stringify(data || {}),
-                headers: extraHeaders,
-            }));
-        }
-        return normalizeDatabaseOperationResult(await this.request(path, {
-            method: "POST",
-            body: JSON.stringify(data || {}),
-            headers: extraHeaders,
-        }));
-    }
-    /**
-     * Execute a registered batch (bulk) database operation. Posts a chunk of
-     * items to the canonical `operations/:name/batch` endpoint (the same one the
-     * client library's `executeBatch` uses — NOT the deprecated `import-bulk`
-     * alias). Used by `databases import-csv`.
-     *
-     * @returns `{ imported, failed }` — DO-level write outcome counts. Per-item
-     *   validation/access failures abort the whole chunk with a 4xx (thrown).
-     */
-    async executeBatch(appId, databaseId, operationName, batch) {
-        return this.post(`/app/${appId}/api/databases/${databaseId}/operations/${encodeURIComponent(operationName)}/batch`, { batch });
-    }
-    /**
-     * Make a request using a specific JWT token instead of the CLI's credentials.
-     * Used for executing operations as a different user.
-     */
-    async requestWithToken(path, token, options = {}) {
-        const credentials = await this.ensureAuthenticated();
-        const url = `${credentials.serverUrl}${path}`;
-        const headers = {
-            Authorization: `Bearer ${token}`,
-            "Content-Type": "application/json",
-            ...(options.headers || {}),
-        };
-        const response = await fetchWithTLS(url, { ...options, headers });
-        const text = await response.text();
-        if (!response.ok) {
-            const parsed = parseErrorResponse(response, text, path);
-            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
-        }
-        return text ? JSON.parse(text) : null;
-    }
-    // ============================================
     // DATABASE INDEXES
     // ============================================
     async listDatabaseIndexes(appId, databaseId, modelName) {
@@ -2082,7 +1906,7 @@ export class ApiClient {
     // Issue #1336 (codex round-1 P2): `dryRun` runs every create-time
     // validation (inline CEL rule lint, manifest shape, schema TOML parse)
     // WITHOUT persisting, so a fresh-type `config push --dry-run` surfaces a
-    // malformed `defaultAccess`/manifest the same way the real POST would.
+    // malformed rule or manifest the same way the real POST would.
     options) {
         const query = options?.dryRun ? "?dryRun=true" : "";
         return this.post(`/app/${appId}/api/databases/types${query}`, data);
@@ -2103,105 +1927,14 @@ export class ApiClient {
         return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}${query}`);
     }
     /**
-     * Issue #666 Phase 3: ask the server to scaffold a TOML schema from
-     * existing ops + DO field introspection. Read-only — does NOT persist.
+     * Issue #666 Phase 3: ask the server to scaffold a TOML schema from the
+     * type's databases (the models each holds, and their fields). Read-only —
+     * does NOT persist.
      */
     async scaffoldDatabaseTypeSchema(appId, databaseType) {
         return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/schema:scaffold`, {});
     }
     // ============================================
-    // DATABASE TYPE OPERATIONS
-    // ============================================
-    async listDatabaseTypeOperations(appId, databaseType) {
-        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations`);
-    }
-    async getDatabaseTypeOperation(appId, databaseType, name) {
-        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations/${encodeURIComponent(name)}`);
-    }
-    async createDatabaseTypeOperation(appId, databaseType, data, 
-    // Issue #813 (1A): when `dryRun` is set the server runs the op-edit gate
-    // without persisting — used by `config push --dry-run` to surface gate
-    // failures the real push would hit. `schemaOverride` lets the gate run
-    // against the schema the SAME push is about to land (so an op that depends
-    // on a new field isn't falsely rejected against the stale stored schema).
-    //
-    // Issue #915 (defect a, follow-up): for a FRESH db-type the parent config
-    // does not exist on the server yet, so the server's "access required"
-    // check has no `defaultAccess` to fall back on. Thread the TOML-declared
-    // type-level `defaultAccess` so an op that omits `access` (intending to
-    // inherit it after the type is created) isn't falsely rejected during the
-    // dry-run. Server only trusts this on the fresh-type dry-run path.
-    options) {
-        const query = options?.dryRun ? "?dryRun=true" : "";
-        let body = data;
-        if (options?.dryRun && options.schemaOverride !== undefined) {
-            body = { ...body, schemaOverride: options.schemaOverride };
-        }
-        if (options?.dryRun && options.defaultAccess !== undefined) {
-            body = { ...body, defaultAccess: options.defaultAccess };
-        }
-        if (options?.dryRun && options.metadataManifestOverride !== undefined) {
-            body = { ...body, metadataManifestOverride: options.metadataManifestOverride };
-        }
-        return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations${query}`, body);
-    }
-    async updateDatabaseTypeOperation(appId, databaseType, name, data, expectedModifiedAt, 
-    // Issue #813 (1A): dry-run runs the op-edit gate without persisting.
-    // `schemaOverride` gates against the schema the same push is landing.
-    // Issue #1336: `metadataManifestOverride` gates the op-access lint against
-    // the manifest the same push is landing (see `createDatabaseTypeOperation`).
-    options) {
-        let body = expectedModifiedAt ? { ...data, expectedModifiedAt } : { ...data };
-        if (options?.dryRun && options.schemaOverride !== undefined) {
-            body = { ...body, schemaOverride: options.schemaOverride };
-        }
-        if (options?.dryRun && options.metadataManifestOverride !== undefined) {
-            body = { ...body, metadataManifestOverride: options.metadataManifestOverride };
-        }
-        const query = options?.dryRun ? "?dryRun=true" : "";
-        return this.patch(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations/${encodeURIComponent(name)}${query}`, body);
-    }
-    async deleteDatabaseTypeOperation(appId, databaseType, name) {
-        return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations/${encodeURIComponent(name)}`);
-    }
-    // ============================================
-    // DATABASE TYPE SUBSCRIPTIONS (#740 / #803)
-    // ============================================
-    //
-    // Transparent passthroughs against the server's type-scoped subscription
-    // routes (GET/POST/PUT/DELETE `/databases/types/:type/subscriptions[/:key]`).
-    // The wire format is authoritative in the controller
-    // (`database-type-subscriptions-controller.ts`): create requires
-    // `subscriptionKey`, `displayName`, `modelName`, `filter` (CEL), `access`
-    // (CEL); optional `description`, `select` (string[]), `emit`
-    // (enter/update/leave subset), `params` (object, ≤5 entries), `status`.
-    //
-    // The list endpoint wraps results in `{ items: [...] }` (unlike operations,
-    // which returns a bare array). We unwrap here so callers get an array,
-    // matching `listDatabaseTypeOperations`.
-    async listDatabaseTypeSubscriptions(appId, databaseType) {
-        const result = await this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions`);
-        if (Array.isArray(result))
-            return result;
-        return Array.isArray(result?.items) ? result.items : [];
-    }
-    async getDatabaseTypeSubscription(appId, databaseType, subscriptionKey) {
-        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`);
-    }
-    async createDatabaseTypeSubscription(appId, databaseType, data) {
-        return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions`, data);
-    }
-    async updateDatabaseTypeSubscription(appId, databaseType, subscriptionKey, data, 
-    // #2731 B10 — optimistic concurrency, as the sibling operation update has
-    // had. Omitted (by `--force`, and by every caller predating it) means the
-    // write stays unconditional.
-    expectedModifiedAt) {
-        return this.put(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`, expectedModifiedAt ? { ...data, expectedModifiedAt } : data);
-    }
-    async deleteDatabaseTypeSubscription(appId, databaseType, subscriptionKey) {
-        return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`);
-    }
-    // ============================================
     // GROUPS
     // ============================================
     async listGroups(appId, params) {
@@ -2213,31 +1946,55 @@ export class ApiClient {
             hasMore: result?.hasMore ?? nextCursor != null,
         };
     }
+    /** One page of one custodian's groups (`app` or `user:<userId>`), through the admin API. */
+    async listGroupsByCustodian(appId, custodian, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/groups`, { custodian, ...(params ?? {}) });
+        const nextCursor = result?.nextCursor;
+        return {
+            items: result?.items ?? [],
+            nextCursor,
+            hasMore: result?.hasMore ?? nextCursor != null,
+        };
+    }
+    /** Transfer a group to `to` (`app` or `user:<userId>`) through the admin API. */
+    async transferGroup(appId, groupId, to) {
+        return this.post(`/admin/api/apps/${appId}/groups/${encodeURIComponent(groupId)}/transfer`, { to });
+    }
+    /**
+     * Create a group through the admin API; `custodian` is `app` or
+     * `user:<userId>`. The server mints the group's id and answers it as
+     * `groupId`.
+     */
     async createGroup(appId, data) {
-        return this.post(`/app/${appId}/api/groups`, data);
+        return this.post(`/admin/api/apps/${appId}/groups`, data);
     }
-    async getGroup(appId, groupType, groupId) {
-        return this.get(`/app/${appId}/api/groups/${groupType}/${groupId}`);
+    /**
+     * A group by id. `groupType` looks a group written before groups were
+     * addressed by id up by its type first (the routes' deprecated
+     * `?groupType=`), as an exported collection's grants still name them.
+     */
+    async getGroup(appId, groupId, options) {
+        return this.get(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}`, options?.groupType ? { groupType: options.groupType } : undefined);
     }
-    async updateGroup(appId, groupType, groupId, data) {
-        return this.patch(`/app/${appId}/api/groups/${groupType}/${groupId}`, data);
+    async updateGroup(appId, groupId, data) {
+        return this.patch(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}`, data);
     }
-    async deleteGroup(appId, groupType, groupId) {
-        return this.delete(`/app/${appId}/api/groups/${groupType}/${groupId}`);
+    async deleteGroup(appId, groupId) {
+        return this.delete(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}`);
     }
     // ============================================
     // GROUP MEMBERS
     // ============================================
     /**
-     * One page of a group's members.
+     * One page of a group's members, with their roles.
      *
      * The route paginates cursor-style (no default limit, cap 200) and reports
      * the boundary, so `groups members list` carries `--limit`/`--cursor` and
      * forwards them (#3646) rather than printing a first page that claims to be
      * the whole membership.
      */
-    async listGroupMembers(appId, groupType, groupId, options) {
-        const result = await this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/members`, {
+    async listGroupMembers(appId, groupId, options) {
+        const result = await this.get(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}/members`, {
             ...(options?.include ? { include: options.include } : {}),
             ...(options?.limit !== undefined ? { limit: options.limit } : {}),
             ...(options?.cursor ? { cursor: options.cursor } : {}),
@@ -2249,17 +2006,23 @@ export class ApiClient {
             hasMore: result?.hasMore ?? nextCursor != null,
         };
     }
-    async addGroupMember(appId, groupType, groupId, data) {
-        return this.post(`/app/${appId}/api/groups/${groupType}/${groupId}/members`, data);
+    /** Add a member through the admin API; `role: "owner"` restores the custodian's owner row. */
+    async addGroupMember(appId, groupId, data) {
+        return this.post(`/admin/api/apps/${appId}/groups/${encodeURIComponent(groupId)}/members`, data);
+    }
+    /** Change a member's role through the admin API, the owner row's included. */
+    async setGroupMemberRole(appId, groupId, userId, role) {
+        return this.patch(`/admin/api/apps/${appId}/groups/${encodeURIComponent(groupId)}/members/${encodeURIComponent(userId)}`, { role });
     }
-    async removeGroupMember(appId, groupType, groupId, userId) {
-        return this.delete(`/app/${appId}/api/groups/${groupType}/${groupId}/members/${userId}`);
+    /** Remove a member through the admin API, the owner row included. */
+    async removeGroupMember(appId, groupId, userId) {
+        return this.delete(`/admin/api/apps/${appId}/groups/${encodeURIComponent(groupId)}/members/${encodeURIComponent(userId)}`);
     }
     // ============================================
     // GROUP RESOURCE LISTINGS
     // ============================================
-    async listGroupDocuments(appId, groupType, groupId) {
-        return this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/documents`);
+    async listGroupDocuments(appId, groupId) {
+        return this.get(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}/documents`);
     }
     // ============================================
     // USER MEMBERSHIPS
@@ -2313,6 +2076,33 @@ export class ApiClient {
     async createCollection(appId, data) {
         return this.post(`/app/${appId}/api/collections`, data);
     }
+    /** One page of one custodian's collections (`app` or `user:<userId>`), through the admin API. */
+    async listCollectionsByCustodian(appId, custodian, params) {
+        const query = { custodian };
+        if (params?.limit !== undefined)
+            query.limit = params.limit;
+        if (params?.cursor)
+            query.cursor = params.cursor;
+        const result = await this.get(`/admin/api/apps/${appId}/collections`, query);
+        const nextCursor = result?.nextCursor;
+        return {
+            items: result?.items ?? [],
+            nextCursor,
+            hasMore: result?.hasMore ?? nextCursor != null,
+        };
+    }
+    /** Transfer a collection to `to` (`app` or `user:<userId>`) through the admin API. */
+    async transferCollection(appId, collectionId, to) {
+        return this.post(`/admin/api/apps/${appId}/collections/${encodeURIComponent(collectionId)}/transfer`, { to });
+    }
+    /**
+     * Create a collection through the admin API, for `custodian` (`app` or
+     * `user:<userId>`; a user custodian holds the owner row). Spends no
+     * create budget.
+     */
+    async createCollectionAsAdmin(appId, data) {
+        return this.post(`/admin/api/apps/${appId}/collections`, data);
+    }
     async getCollection(appId, collectionId) {
         return this.get(`/app/${appId}/api/collections/${collectionId}`);
     }
@@ -2359,41 +2149,30 @@ export class ApiClient {
         };
     }
     // ============================================
-    // COLLECTION ACCESS (GROUPS + MEMBERS)
+    // COLLECTION MEMBERS (USERS + GROUPS)
     // ============================================
-    async getCollectionAccess(appId, collectionId) {
-        return this.get(`/app/${appId}/api/collections/${collectionId}/access`);
-    }
-    async grantCollectionGroupPermission(appId, collectionId, data) {
-        return this.post(`/app/${appId}/api/collections/${collectionId}/group-permissions`, data);
-    }
-    async revokeCollectionGroupPermission(appId, collectionId, groupType, groupId) {
-        return this.delete(`/app/${appId}/api/collections/${collectionId}/group-permissions/${groupType}/${groupId}`);
+    /**
+     * Every member of a collection, users and groups as principals with their
+     * roles, in one answer.
+     */
+    async listCollectionMembers(appId, collectionId) {
+        const result = await this.get(`/app/${appId}/api/collections/${encodeURIComponent(collectionId)}/members`);
+        return { items: result?.items ?? [], hasMore: Boolean(result?.hasMore) };
     }
+    /**
+     * Add a user or a group to a collection through the admin API, with a role;
+     * `role: "owner"` restores the custodian's owner row.
+     */
     async addCollectionMember(appId, collectionId, data) {
-        return this.post(`/app/${appId}/api/collections/${collectionId}/members`, data);
-    }
-    async removeCollectionMember(appId, collectionId, userId) {
-        return this.delete(`/app/${appId}/api/collections/${collectionId}/members/${userId}`);
-    }
-    // ============================================
-    // COLLECTION TYPE CONFIGS
-    // ============================================
-    async listCollectionTypeConfigs(appId) {
-        return this.get(`/app/${appId}/api/collection-type-configs`);
+        return this.post(`/admin/api/apps/${appId}/collections/${encodeURIComponent(collectionId)}/members`, data);
     }
-    async getCollectionTypeConfig(appId, collectionType) {
-        return this.get(`/app/${appId}/api/collection-type-configs/${collectionType}`);
+    /** Change a member's role through the admin API, the owner row's included. */
+    async setCollectionMemberRole(appId, collectionId, principal, role) {
+        return this.patch(`/admin/api/apps/${appId}/collections/${encodeURIComponent(collectionId)}/members/${encodeURIComponent(principal)}`, { role });
     }
-    async createCollectionTypeConfig(appId, data) {
-        return this.post(`/app/${appId}/api/collection-type-configs`, data);
-    }
-    async updateCollectionTypeConfig(appId, collectionType, data, expectedModifiedAt) {
-        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
-        return this.patch(`/app/${appId}/api/collection-type-configs/${collectionType}`, body);
-    }
-    async deleteCollectionTypeConfig(appId, collectionType) {
-        return this.delete(`/app/${appId}/api/collection-type-configs/${collectionType}`);
+    /** Remove a user or `group:<groupId>` through the admin API, the owner row included. */
+    async removeCollectionMember(appId, collectionId, principal) {
+        return this.delete(`/admin/api/apps/${appId}/collections/${encodeURIComponent(collectionId)}/members/${encodeURIComponent(principal)}`);
     }
     // ============================================
     // METADATA CATEGORY CONFIGS (issue #1304, P-B)
@@ -2464,25 +2243,6 @@ export class ApiClient {
         return this.post(`/app/${appId}/api/rule-sets/debug`, data);
     }
     // ============================================
-    // GROUP TYPE CONFIGS
-    // ============================================
-    async listGroupTypeConfigs(appId) {
-        return this.get(`/app/${appId}/api/group-type-configs`);
-    }
-    async getGroupTypeConfig(appId, groupType) {
-        return this.get(`/app/${appId}/api/group-type-configs/${groupType}`);
-    }
-    async createGroupTypeConfig(appId, data) {
-        return this.post(`/app/${appId}/api/group-type-configs`, data);
-    }
-    async updateGroupTypeConfig(appId, groupType, data, expectedModifiedAt) {
-        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
-        return this.patch(`/app/${appId}/api/group-type-configs/${groupType}`, body);
-    }
-    async deleteGroupTypeConfig(appId, groupType) {
-        return this.delete(`/app/${appId}/api/group-type-configs/${groupType}`);
-    }
-    // ============================================
     // DOCUMENT EXPORT / IMPORT
     // ============================================
     async exportDocumentState(appId, documentId) {
@@ -2519,51 +2279,6 @@ export class ApiClient {
     async importDocumentState(appId, documentId, stateBase64) {
         return this.post(`/app/${appId}/api/documents/${documentId}/import/state`, { state: stateBase64 });
     }
-    /**
-     * Upload one artifact of a large document's import chain (#2816,
-     * behavior 20).
-     *
-     * The bytes travel raw and unmodified: the manifest's digest is over the
-     * STORED bytes, so re-encoding a chunk here would fail its own verification
-     * on install. The query says which artifact it is — the server derives the
-     * key from the document it belongs to, so nothing here composes one.
-     */
-    async uploadDocumentChainArtifact(appId, documentId, query, body) {
-        const credentials = await this.ensureAuthenticated();
-        const search = new URLSearchParams();
-        for (const [key, value] of Object.entries(query)) {
-            search.set(key, String(value));
-        }
-        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}` +
-            `/import/chain/artifact?${search.toString()}`;
-        const headers = {
-            Authorization: `Bearer ${credentials.accessToken}`,
-            "Content-Type": "application/octet-stream",
-        };
-        if (credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
-        const response = await fetchWithTLS(url, {
-            method: "POST",
-            headers,
-            body: body,
-        });
-        if (!response.ok) {
-            // #3403 — through the shared parser: reading `error` alone dropped the
-            // envelope's `code` and `details`, so the refusal reached the operator
-            // (and `primitive documents import`) with nothing to branch on.
-            throw await blobFailure(response, "Failed to upload import artifact: ");
-        }
-        return await response.json().catch(() => ({}));
-    }
-    /** Start installing an uploaded chain (#2816, behavior 20). */
-    async installDocumentChain(appId, documentId, plan) {
-        return this.post(`/app/${appId}/api/documents/${documentId}/import/chain`, plan);
-    }
-    /** How far a document's chain install has got (#2816, behavior 20). */
-    async getDocumentChainInstall(appId, documentId) {
-        return this.get(`/app/${appId}/api/documents/${documentId}/import/chain`);
-    }
     async getDocument(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}`);
     }
@@ -2603,11 +2318,17 @@ export class ApiClient {
      * through the caller's document permission (reader+) or the app-admin arm.
      * Returns the unified `{ items, hasMore, nextCursor? }` envelope. The cursor
      * is an opaque token — feed `nextCursor` back as `cursor` for the next page.
+     * `limit` is 100 records when omitted and at most 10000; it is forwarded
+     * unparsed (a string from the command line) so the server validates it.
      */
     async queryDocumentRecords(appId, documentId, modelName, queryOptions) {
         const query = {};
         if (queryOptions?.filter)
             query.filter = JSON.stringify(queryOptions.filter);
+        if (queryOptions?.sort !== undefined)
+            query.sort = JSON.stringify(queryOptions.sort);
+        if (queryOptions?.include !== undefined)
+            query.include = JSON.stringify(queryOptions.include);
         if (queryOptions?.documentFormat !== undefined) {
             query.documentFormat = queryOptions.documentFormat;
         }
@@ -2636,12 +2357,14 @@ export class ApiClient {
     /**
      * Aggregate records in a document model (issue #2437) — the documents twin
      * of {@link aggregateDatabaseRecords}. `POST documents/:id/records/:model/aggregate`
-     * with `{ options: { operations, groupBy?, filter? } }`, answering `{ result }`
-     * in the same shape as the database endpoint.
+     * with `{ options: { operations, groupBy?, filter?, sort?, limit? } }`,
+     * answering `{ result }` in the same shape as the database endpoint.
      *
-     * `groupBy` takes plain field names only: StringSet facet grouping and
-     * `{ field, contains }` membership grouping are database-only, which is why
-     * this signature is narrower than the databases one.
+     * `groupBy` takes plain field names and period levels `{ field, period }`
+     * (keyed `<field>_<period>` in a row's `group`). On a db3 (a format-3
+     * document) a StringSet field name is a facet, `{ field, contains }` a
+     * membership, and `sort` and `limit` order and bound the groups; a format-1
+     * document refuses those four with a 400.
      */
     async aggregateDocumentRecords(appId, documentId, modelName, options, extra) {
         return this.post(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/aggregate` +
@@ -2654,6 +2377,23 @@ export class ApiClient {
     async getDocumentStats(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/stats`);
     }
+    /**
+     * A record-log document's room (#4306): `GET documents/:id/room` →
+     * `{ ok, appId, documentId, documentFormat, room }`, `room` null for a
+     * format that has no record room. With `refused` (#4310), the answer also
+     * carries a page of that bulk load's refused rows. App admins only.
+     */
+    async getDocumentRoom(appId, documentId, query = {}) {
+        const params = new URLSearchParams();
+        if (query.refused !== undefined)
+            params.set("refused", query.refused);
+        if (query.limit !== undefined)
+            params.set("limit", String(query.limit));
+        if (query.cursor !== undefined)
+            params.set("cursor", query.cursor);
+        const search = params.toString();
+        return this.get(`/app/${appId}/api/documents/${documentId}/room${search ? `?${search}` : ""}`);
+    }
     /**
      * A large document's snapshot builds, newest first, one page (#3432).
      * `GET documents/:id/snapshots` → `{ items, hasMore, nextCursor? }`.
@@ -2687,9 +2427,13 @@ export class ApiClient {
     async getDocumentIngest(appId, documentId, sessionId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/ingest/${encodeURIComponent(sessionId)}`);
     }
-    /** Open a bulk-load session on a large document (#3435, criterion 9). */
-    async createDocumentIngest(appId, documentId) {
-        return this.post(`/app/${appId}/api/documents/${documentId}/ingest`, {});
+    /**
+     * Open a bulk-load session on a large document (#3435, criterion 9). A
+     * record-log (format 3) document's load takes `reserveEpoch`, `mode` and a
+     * refresh's `models` (#4310); `{}` keeps every format's defaults.
+     */
+    async createDocumentIngest(appId, documentId, options = {}) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/ingest`, options);
     }
     /**
      * Upload one chunk of a bulk-load session's artifact (#3435).
@@ -2700,6 +2444,10 @@ export class ApiClient {
      * would name one the body does not use.
      */
     async uploadDocumentIngestChunk(appId, documentId, sessionId, chunk) {
+        return this.uploadIngestChunkAt(`/app/${appId}/api/documents/${documentId}`, sessionId, chunk);
+    }
+    /** A chunk upload to `<base>/ingest/<session>/chunks`: the documents route or its db3 mount. */
+    async uploadIngestChunkAt(base, sessionId, chunk) {
         const credentials = await this.ensureAuthenticated();
         const form = new FormData();
         form.set("model", chunk.model);
@@ -2711,18 +2459,15 @@ export class ApiClient {
         form.set("firstId", chunk.firstId);
         form.set("lastId", chunk.lastId);
         form.set("chunk", new Blob([chunk.body]), `${chunk.index}.ndjson.gz`);
-        const headers = {
-            Authorization: `Bearer ${credentials.accessToken}`,
-        };
-        if (credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
-        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}` +
-            `/ingest/${encodeURIComponent(sessionId)}/chunks`;
-        const response = await fetchWithTLS(url, {
-            method: "POST",
-            headers,
-            body: form,
+        const url = `${credentials.serverUrl}${base}/ingest/${encodeURIComponent(sessionId)}/chunks`;
+        const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+            };
+            if (credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+            }
+            return { method: "POST", headers, body: form };
         });
         const text = await response.text();
         let result = {};
@@ -2798,6 +2543,246 @@ export class ApiClient {
         return this.post(`/app/${appId}/api/documents/${documentId}/records/bulk` +
             this.documentFormatQuery(extra?.documentFormat), { operations });
     }
+    // ============================================
+    // DB3 (format-3 documents)
+    // ============================================
+    /** `/app/<app>/api/db3/<id>`, the id encoded: every `db3.*` route's prefix. */
+    db3Path(appId, db3Id) {
+        return `/app/${appId}/api/db3/${encodeURIComponent(db3Id)}`;
+    }
+    /** `GET db3/:id/indexes` → `{ indexes }`, sorted by name. */
+    async listDb3Indexes(appId, db3Id) {
+        return this.get(`${this.db3Path(appId, db3Id)}/indexes`);
+    }
+    /**
+     * `POST db3/:id/indexes` with `{ model, field | fields, unique?, name? }` →
+     * `{ index }`. The route applies the registration rules.
+     */
+    async registerDb3Index(appId, db3Id, body) {
+        return this.post(`${this.db3Path(appId, db3Id)}/indexes`, body);
+    }
+    /** `DELETE db3/:id/indexes/:name` → `{ ok, name }`. */
+    async dropDb3Index(appId, db3Id, name) {
+        return this.delete(`${this.db3Path(appId, db3Id)}/indexes/${encodeURIComponent(name)}`);
+    }
+    /** The db3 mount of {@link queryDocumentRecords}: `GET db3/:id/records/:model`. */
+    async queryDb3Records(appId, db3Id, modelName, queryOptions) {
+        const query = {};
+        if (queryOptions?.filter)
+            query.filter = JSON.stringify(queryOptions.filter);
+        if (queryOptions?.sort !== undefined)
+            query.sort = JSON.stringify(queryOptions.sort);
+        if (queryOptions?.include !== undefined)
+            query.include = JSON.stringify(queryOptions.include);
+        if (queryOptions?.limit !== undefined)
+            query.limit = queryOptions.limit;
+        if (queryOptions?.cursor)
+            query.cursor = queryOptions.cursor;
+        const raw = await this.get(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}`, query);
+        return normalizeCliListEnvelope(raw);
+    }
+    /** The db3 mount of {@link countDocumentRecords}: `GET db3/:id/records/:model/count`. */
+    async countDb3Records(appId, db3Id, modelName, queryOptions) {
+        const query = {};
+        if (queryOptions?.filter)
+            query.filter = JSON.stringify(queryOptions.filter);
+        return this.get(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/count`, query);
+    }
+    /** The db3 mount of {@link aggregateDocumentRecords}: `POST db3/:id/records/:model/aggregate`. */
+    async aggregateDb3Records(appId, db3Id, modelName, options) {
+        return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/aggregate`, { options });
+    }
+    /** The db3 mount of {@link saveDocumentRecord}: `POST db3/:id/records/:model`. */
+    async saveDb3Record(appId, db3Id, modelName, body) {
+        return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}`, body);
+    }
+    /** The db3 mount of {@link patchDocumentRecord}: `PATCH db3/:id/records/:model/:recordId`. */
+    async patchDb3Record(appId, db3Id, modelName, recordId, body) {
+        return this.patch(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}`, body);
+    }
+    /** The db3 mount of {@link deleteDocumentRecord}: `DELETE db3/:id/records/:model/:recordId`. */
+    async deleteDb3Record(appId, db3Id, modelName, recordId) {
+        return this.delete(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}`);
+    }
+    /** The db3 mount of {@link bulkDocumentRecords}: `POST db3/:id/records/bulk`. */
+    async bulkDb3Records(appId, db3Id, operations) {
+        return this.post(`${this.db3Path(appId, db3Id)}/records/bulk`, { operations });
+    }
+    /** The db3 mount of {@link getDocumentSchema}: `GET db3/:id/schema`. */
+    async getDb3Schema(appId, db3Id) {
+        return this.get(`${this.db3Path(appId, db3Id)}/schema`);
+    }
+    /** `?limit=&cursor=` for a listing. */
+    pageQuery(options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        const query = params.toString();
+        return query ? `?${query}` : "";
+    }
+    /** `GET db3/:id/ingest` (#4889): a db3's bulk-load sessions, newest first. */
+    async listDb3Ingests(appId, db3Id, options = {}) {
+        return this.get(`${this.db3Path(appId, db3Id)}/ingest${this.pageQuery(options)}`);
+    }
+    /** `GET db3/:id/ingest/:sessionId` (#4889). */
+    async getDb3Ingest(appId, db3Id, sessionId) {
+        return this.get(`${this.db3Path(appId, db3Id)}/ingest/${encodeURIComponent(sessionId)}`);
+    }
+    /** `POST db3/:id/ingest` (#4889): open a bulk-load session; `{}` keeps the defaults. */
+    async createDb3Ingest(appId, db3Id, options = {}) {
+        return this.post(`${this.db3Path(appId, db3Id)}/ingest`, options);
+    }
+    /** `POST db3/:id/ingest/:sessionId/chunks` (#4889): one chunk, multipart, as the documents upload sends it. */
+    async uploadDb3IngestChunk(appId, db3Id, sessionId, chunk) {
+        return this.uploadIngestChunkAt(this.db3Path(appId, db3Id), sessionId, chunk);
+    }
+    /** `POST db3/:id/ingest/:sessionId/commit` (#4889). */
+    async commitDb3Ingest(appId, db3Id, sessionId) {
+        return this.post(`${this.db3Path(appId, db3Id)}/ingest/${encodeURIComponent(sessionId)}/commit`, {});
+    }
+    /** `POST db3/:id/ingest/:sessionId/abort` (#4889). */
+    async abortDb3Ingest(appId, db3Id, sessionId) {
+        return this.post(`${this.db3Path(appId, db3Id)}/ingest/${encodeURIComponent(sessionId)}/abort`, {});
+    }
+    /** `GET db3/:id/snapshots` (#4889): a db3's segment exports, newest first. */
+    async listDb3Snapshots(appId, db3Id, options = {}) {
+        return this.get(`${this.db3Path(appId, db3Id)}/snapshots${this.pageQuery(options)}`);
+    }
+    /** `GET db3/:id/snapshots/:segmentId` (#4889). */
+    async getDb3Snapshot(appId, db3Id, segmentId) {
+        return this.get(`${this.db3Path(appId, db3Id)}/snapshots/${encodeURIComponent(segmentId)}`);
+    }
+    /** `POST db3/:id/snapshots` (#4889): start a segment export. */
+    async requestDb3Snapshot(appId, db3Id) {
+        return this.post(`${this.db3Path(appId, db3Id)}/snapshots`, {});
+    }
+    /** `GET db3/:id/export/chain` (#4889): the current segment, signed for download. */
+    async exportDb3Chain(appId, db3Id) {
+        return this.get(`${this.db3Path(appId, db3Id)}/export/chain`);
+    }
+    /** `GET db3/:id/blobs` (#4889): one page of a db3's blobs. */
+    async listDb3Blobs(appId, db3Id, params) {
+        return this.get(`${this.db3Path(appId, db3Id)}/blobs`, params);
+    }
+    /** `GET db3/:id/blobs/:blobId/download` (#4889): a blob's bytes. */
+    async downloadDb3Blob(appId, db3Id, blobId) {
+        return this.downloadBlobAt(this.db3Path(appId, db3Id), blobId);
+    }
+    /** `PUT db3/:id/blobs/:blobId` (#4889): a blob under its own id, as the documents upload sends it. */
+    async uploadDb3Blob(appId, db3Id, blobId, data, meta) {
+        return this.uploadBlobAt(this.db3Path(appId, db3Id), blobId, data, meta);
+    }
+    /** The db3 mount of {@link getDocumentRoom}: `GET db3/:id/room`. App admins only. */
+    async getDb3Room(appId, db3Id, query = {}) {
+        const params = new URLSearchParams();
+        if (query.refused !== undefined)
+            params.set("refused", query.refused);
+        if (query.limit !== undefined)
+            params.set("limit", String(query.limit));
+        if (query.cursor !== undefined)
+            params.set("cursor", query.cursor);
+        const search = params.toString();
+        return this.get(`${this.db3Path(appId, db3Id)}/room${search ? `?${search}` : ""}`);
+    }
+    /**
+     * `POST db3` (#4804): create a db3 and answer it, `{ id, title, createdBy,
+     * createdAt, modifiedAt, custodian, sync, type, tags }`. Without `custodian`
+     * an admin token's create is held by the app. `id` keeps a caller-chosen id
+     * (#4921), refused `DB3_ID_EXISTS` when the app holds it.
+     */
+    async createDb3(appId, body) {
+        return this.post(`/app/${appId}/api/db3`, body);
+    }
+    /** `GET db3/:id` (#4804): the db3, with the caller's grant when it reads it through one. */
+    async getDb3(appId, db3Id) {
+        return this.get(this.db3Path(appId, db3Id));
+    }
+    /** `DELETE db3/:id` (#4804): the documents delete for a db3. */
+    async deleteDb3(appId, db3Id) {
+        return this.delete(this.db3Path(appId, db3Id));
+    }
+    /** The db3 mount of {@link getDocumentStats}: `GET db3/:id/stats`. */
+    async getDb3Stats(appId, db3Id) {
+        return this.get(`${this.db3Path(appId, db3Id)}/stats`);
+    }
+    /**
+     * `POST db3/:id/records/:model/:recordId/increment` (#4797): add each of
+     * `fields` to the record's field, answering `{ record, values }`.
+     */
+    async incrementDb3Record(appId, db3Id, modelName, recordId, body) {
+        return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}/increment`, body);
+    }
+    /** `GET db3/:id/sync` (#4799): `{ id, sync }`. */
+    async getDb3Sync(appId, db3Id) {
+        return this.get(`${this.db3Path(appId, db3Id)}/sync`);
+    }
+    /** `PUT db3/:id/sync` (#4799): `{ id, sync, changed }`. */
+    async setDb3Sync(appId, db3Id, sync) {
+        return this.put(`${this.db3Path(appId, db3Id)}/sync`, { sync });
+    }
+    /** `GET db3/:id/app-access` (#4801): `{ id, level }`, the level every user of the app holds, or null. */
+    async getDb3AppAccess(appId, db3Id) {
+        return this.get(`${this.db3Path(appId, db3Id)}/app-access`);
+    }
+    /** `PUT db3/:id/app-access` (#4801): grant the db3 to every user of the app, or remove the grant with null. */
+    async setDb3AppAccess(appId, db3Id, level) {
+        return this.put(`${this.db3Path(appId, db3Id)}/app-access`, { level });
+    }
+    /** One custodian's db3s through the admin API (#4800): `custodian` is `app` or `user:<userId>`. */
+    async listDb3ByCustodian(appId, custodian, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/db3`, { custodian, ...(params ?? {}) });
+        const nextCursor = result?.nextCursor;
+        return { items: result?.items ?? [], nextCursor, hasMore: result?.hasMore ?? nextCursor != null };
+    }
+    /** Transfer a db3 to `to` (`app` or `user:<userId>`) through the admin API (#4804). */
+    async transferDb3(appId, db3Id, to) {
+        return this.post(`/admin/api/apps/${appId}/db3/${encodeURIComponent(db3Id)}/transfer`, { to });
+    }
+    /** Remove or restore a db3's owner row through the admin API (#4804): `{ id, custodian, ownerRow, changed }`. */
+    async setDb3OwnerRow(appId, db3Id, present) {
+        return this.put(`/admin/api/apps/${appId}/db3/${encodeURIComponent(db3Id)}/owner-row`, { present });
+    }
+    /** `GET db3/:id/type` (#4802): the type the db3's row names, its revision, and what its room holds. */
+    async getDb3Type(appId, db3Id) {
+        return this.get(`${this.db3Path(appId, db3Id)}/type`);
+    }
+    /** `PUT db3/:id/type` (#4802): attach a type, installing its current revision whole or refusing it whole. */
+    async attachDb3Type(appId, db3Id, type) {
+        return this.put(`${this.db3Path(appId, db3Id)}/type`, { type });
+    }
+    /** `/app/<app>/api/db3-types/<name>`, the name encoded (#4802). */
+    db3TypePath(appId, name) {
+        return `/app/${appId}/api/db3-types/${encodeURIComponent(name)}`;
+    }
+    /** `GET db3-types` (#4802): the app's db3 types, each with its revision. */
+    async listDb3Types(appId) {
+        return this.get(`/app/${appId}/api/db3-types`);
+    }
+    /** `GET db3-types/:name` (#4802). */
+    async getDb3TypeConfig(appId, name) {
+        return this.get(this.db3TypePath(appId, name));
+    }
+    /**
+     * `PUT db3-types/:name` (#4802): create or update the type, and push its new
+     * revision to every db3 of it. `dryRun` judges the body and persists nothing.
+     */
+    async pushDb3Type(appId, name, data, options) {
+        return this.put(`${this.db3TypePath(appId, name)}${options?.dryRun ? "?dryRun=true" : ""}`, data);
+    }
+    /** `DELETE db3-types/:name` (#4802): refused while a db3 is of the type. */
+    async deleteDb3Type(appId, name) {
+        return this.delete(this.db3TypePath(appId, name));
+    }
+    /** `GET db3-types/:name/push-status` (#4802): a push's outcome per db3; the latest without `runId`. */
+    async getDb3TypePushStatus(appId, name, runId) {
+        return this.get(`${this.db3TypePath(appId, name)}/push-status${runId ? `?runId=${encodeURIComponent(runId)}` : ""}`);
+    }
+    /** `POST db3-types/:name/push?runId=` (#4802): push the current revision again to a run's refused and failed db3s. */
+    async retryDb3TypePush(appId, name, runId) {
+        return this.post(`${this.db3TypePath(appId, name)}/push?runId=${encodeURIComponent(runId)}`, {});
+    }
     async createDocument(appId, data) {
         return this.post(`/app/${appId}/api/documents`, data);
     }
@@ -2853,12 +2838,21 @@ export class ApiClient {
     async listDocumentPendingInvitations(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/pending-invitations`);
     }
-    async listDocumentBlobs(appId, documentId) {
-        return this.get(`/app/${appId}/api/documents/${documentId}/blobs`);
+    /**
+     * One page of a document's uploaded blobs (the `{ items, hasMore,
+     * nextCursor? }` envelope); pass the previous page's `nextCursor` for the
+     * next.
+     */
+    async listDocumentBlobs(appId, documentId, params) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/blobs`, params);
     }
     async downloadBlob(appId, documentId, blobId) {
+        return this.downloadBlobAt(`/app/${appId}/api/documents/${documentId}`, blobId);
+    }
+    /** A blob's bytes from `<base>/blobs/<id>/download`: the documents route or its db3 mount. */
+    async downloadBlobAt(base, blobId) {
         const credentials = await this.ensureAuthenticated();
-        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}/blobs/${blobId}/download`;
+        const url = `${credentials.serverUrl}${base}/blobs/${blobId}/download`;
         const headers = {
             Authorization: `Bearer ${credentials.accessToken}`,
         };
@@ -2873,8 +2867,37 @@ export class ApiClient {
         return Buffer.from(arrayBuffer);
     }
     async uploadBlob(appId, documentId, blobId, data, meta) {
+        return this.uploadBlobAt(`/app/${appId}/api/documents/${documentId}`, blobId, data, meta);
+    }
+    /** A blob PUT to `<base>/blobs/<id>`: the documents route or its db3 mount. */
+    async uploadBlobAt(base, blobId, data, meta) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}${base}/blobs/${blobId}`;
+        const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+                "Content-Type": meta.contentType,
+                "X-Blob-Filename": encodeURIComponent(meta.filename),
+                "X-Blob-Size": String(data.length),
+                "X-Blob-Sha256": meta.sha256,
+            };
+            if (credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+            }
+            return { method: "PUT", headers, body: data };
+        });
+        if (!response.ok) {
+            throw await blobFailure(response, "Failed to upload blob: ");
+        }
+        return response.json();
+    }
+    /**
+     * Upload a file to an agent session by `sessionId` (#4585): the document
+     * blob upload's headers and body, on the session's attachment route.
+     */
+    async uploadAgentSessionAttachment(appId, sessionId, blobId, data, meta) {
         const credentials = await this.ensureAuthenticated();
-        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}/blobs/${blobId}`;
+        const url = `${credentials.serverUrl}/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(blobId)}`;
         const headers = {
             Authorization: `Bearer ${credentials.accessToken}`,
             "Content-Type": meta.contentType,
@@ -2885,19 +2908,64 @@ export class ApiClient {
         if (credentials.globalAdminAppId) {
             headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
         }
-        const response = await fetchWithTLS(url, {
-            method: "PUT",
-            headers,
-            body: data,
-        });
+        const response = await fetchWithTLS(url, { method: "PUT", headers, body: data });
         if (!response.ok) {
-            throw await blobFailure(response, "Failed to upload blob: ");
+            throw await blobFailure(response, "Failed to upload attachment: ");
         }
         return response.json();
     }
+    /** Download an agent session's file by `sessionId` (#4585). */
+    async downloadAgentSessionAttachment(appId, sessionId, blobId) {
+        const response = await this.agentSessionAttachmentRead("GET", appId, sessionId, blobId);
+        if (!response.ok) {
+            throw await blobFailure(response, "Failed to download attachment: ");
+        }
+        return Buffer.from(await response.arrayBuffer());
+    }
+    /**
+     * An agent session file's download headers (lower-cased names) by
+     * `sessionId` (#4585). A refusal has no body, so it fails with the status
+     * alone and no code.
+     */
+    async headAgentSessionAttachment(appId, sessionId, blobId) {
+        const response = await this.agentSessionAttachmentRead("HEAD", appId, sessionId, blobId);
+        if (!response.ok && response.status !== 304) {
+            throw new ApiError(`Failed to read attachment headers: HTTP ${response.status}`, response.status);
+        }
+        const headers = {};
+        response.headers.forEach((value, name) => {
+            headers[name.toLowerCase()] = value;
+        });
+        return { status: response.status, headers };
+    }
+    async agentSessionAttachmentRead(method, appId, sessionId, blobId) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(blobId)}/download`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        return fetchWithTLS(url, { method, headers });
+    }
     async listDocumentAliases(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/aliases`);
     }
+    /**
+     * The document a user's alias points at, or null when the user holds no
+     * alias under that key (#4148).
+     */
+    async getDocumentAlias(appId, aliasScope, aliasKey, userId) {
+        try {
+            return await this.get(`/app/${appId}/api/document-aliases/${aliasScope}/${encodeURIComponent(aliasKey)}`, { userId });
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.statusCode === 404)
+                return null;
+            throw error;
+        }
+    }
     async setDocumentAlias(appId, aliasScope, aliasKey, documentId, ownerUserId, mustNotExist) {
         return this.put(`/app/${appId}/api/document-aliases/${aliasScope}/${encodeURIComponent(aliasKey)}`, {
             documentId,
@@ -3042,21 +3110,19 @@ export class ApiClient {
     async uploadBucketBlob(appId, bucketIdOrKey, data, meta) {
         const credentials = await this.ensureAuthenticated();
         const url = `${credentials.serverUrl}/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs`;
-        const headers = {
-            Authorization: `Bearer ${credentials.accessToken}`,
-            "Content-Type": meta.contentType,
-            "X-Blob-Filename": encodeURIComponent(meta.filename),
-        };
-        if (meta.tags && meta.tags.length > 0) {
-            headers["X-Blob-Tags"] = JSON.stringify(meta.tags);
-        }
-        if (credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
-        const response = await fetchWithTLS(url, {
-            method: "POST",
-            headers,
-            body: data,
+        const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+                "Content-Type": meta.contentType,
+                "X-Blob-Filename": encodeURIComponent(meta.filename),
+            };
+            if (meta.tags && meta.tags.length > 0) {
+                headers["X-Blob-Tags"] = JSON.stringify(meta.tags);
+            }
+            if (credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+            }
+            return { method: "POST", headers, body: data };
         });
         if (!response.ok) {
             throw await blobFailure(response, "Failed to upload blob: ");