primitive-admin 1.2.0-alpha.3 → 1.2.0-alpha.5

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

@@ -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;
@@ -125,55 +134,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);
@@ -188,55 +157,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.
@@ -293,8 +213,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);
             }
@@ -383,24 +304,9 @@ export class ApiClient {
         if (response.status === 409 && parsed.code === "CONFLICT") {
             return new ConflictError(parsed.message, serverModifiedAt, expectedModifiedAt, detailsRecord);
         }
-        if (response.status === 409 && parsed.code === "OPS_EXIST") {
-            return new OpsExistError(parsed.message, detailsRecord);
-        }
         if (response.status === 400 && parsed.code === "TOML_PARSE_ERROR") {
             return new TomlParseError(parsed.message, detailsRecord);
         }
-        if (response.status === 422 && parsed.code === "SCHEMA_REQUIRED") {
-            return new SchemaRequiredError(parsed.message, detailsRecord);
-        }
-        if (response.status === 422 && parsed.code === "OPERATION_REFERENCES_UNDEFINED") {
-            return new OperationRefError(parsed.message, detailsRecord);
-        }
-        if (response.status === 422 && parsed.code === "SCHEMA_BREAKS_OPERATIONS") {
-            return new SchemaBreaksOpsError(parsed.message, detailsRecord);
-        }
-        if (response.status === 422 && parsed.code === "SCHEMA_HAS_UNCHECKABLE_OPS") {
-            return new SchemaHasUncheckableOpsError(parsed.message, detailsRecord);
-        }
         return new ApiError(parsed.message, response.status, parsed.code, parsed.details);
     }
     /**
@@ -1140,10 +1046,9 @@ export class ApiClient {
     // ============================================
     /**
      * 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`, {
@@ -1529,6 +1434,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) {
@@ -1563,6 +1475,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) {
@@ -2126,72 +2043,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) {
@@ -2224,7 +2075,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);
@@ -2245,105 +2096,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) {
@@ -2661,51 +2421,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}`);
     }
@@ -2796,6 +2511,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? }`.
@@ -2829,9 +2561,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).