dataiku-sdk 3.2.0 → 3.4.0

package/dist/src/resources/data-collections.d.ts

@@ -0,0 +1,118 @@
+import { BaseResource } from "./base.js";
+/**
+ * Data collections are instance-level curated groupings of DSS objects
+ * (datasets, saved models, agents, fine-tuned models, agent tools, semantic
+ * models) shared across projects.
+ *
+ * @see https://doc.dataiku.com/dss/api/15/rest/ (Data Collections section)
+ */
+export type DataCollectionObjectReferenceType = "DATASET" | "SAVED_MODEL" | "FINE_TUNED_MODEL" | "AGENT" | "AGENT_TOOL" | "SEMANTIC_MODEL" | (string & {});
+export interface DataCollectionPermission extends Record<string, unknown> {
+    /** Name of the user this permission applies to (exclusive with group). */
+    user?: string;
+    /** Name of the group this permission applies to (exclusive with user). */
+    group?: string;
+    /** true if the permission grants administrator access. */
+    admin?: boolean;
+    /** true if the permission grants contributor access. */
+    write?: boolean;
+    /** true if the permission grants member access. */
+    read?: boolean;
+}
+export interface DataCollectionSummary extends Record<string, unknown> {
+    /** Name of the collection. */
+    displayName?: string;
+    /** Color of the collection (#RRGBB syntax). */
+    color?: string | null;
+    /** The description of the collection (markdown). */
+    description?: string | null;
+    /** List of tags of the collection. */
+    tags?: string[] | null;
+    /** Id of the collection. */
+    id?: string;
+    /** Number of objects in the collection. */
+    itemCount?: number;
+    /** Number of datasets in the collection. */
+    datasetsCount?: number;
+    /** Number of saved models in the collection, excluding agents and fine tuned models. */
+    savedModelsCount?: number;
+    /** Number of fine tuned models in the collection. */
+    fineTunedModelsCount?: number;
+    /** Number of agents in the collection. */
+    agentsCount?: number;
+    /** Number of agent tools in the collection. */
+    agentToolsCount?: number;
+    /** Number of semantic models in the collection. */
+    semanticModelsCount?: number;
+    /** Timestamp of the last collection modification. */
+    lastModifiedOn?: number;
+}
+export interface DataCollectionSettings extends Record<string, unknown> {
+    /** Id of the collection. */
+    id?: string;
+    /** Name of the collection. */
+    displayName: string;
+    /** Color of the collection (#RRGGBB syntax). */
+    color?: string | null;
+    /** The description of the collection (markdown). */
+    description?: string | null;
+    /** List of tags of the collection. */
+    tags?: string[] | null;
+    /** List of permissions of the collection (READER, CONTRIBUTOR or ADMIN). */
+    permissions?: DataCollectionPermission[] | null;
+}
+export interface DataCollectionCreateRequest extends Omit<DataCollectionSettings, "id"> {
+    /**
+     * Id of the Collection (a random id is generated if not provided).
+     * Must match the [A-Za-z0-9]{8} server-side format when provided.
+     */
+    id?: string;
+}
+/**
+ * An object inside a collection: a reference to a DSS object hosted by a
+ * project. The documented shape covers datasets; `type` accepts the other
+ * collection member kinds the instance may report.
+ */
+export interface DataCollectionObject extends Record<string, unknown> {
+    /** The type of this object (e.g. "DATASET"). */
+    type: DataCollectionObjectReferenceType;
+    /** The key of the project hosting the object. */
+    projectKey: string;
+    /** The id (name) of the object in its project. */
+    id: string;
+}
+export declare class DataCollectionsResource extends BaseResource {
+    /** List the collections on which the API key has READ privilege. */
+    list(): Promise<DataCollectionSummary[]>;
+    /**
+     * Create a collection. The creating user is added as an administrator.
+     * Requires the mayCreateDataCollections global permission. DSS returns
+     * `{ msg, id }`; the created id is surfaced to the caller.
+     */
+    create(body: DataCollectionCreateRequest): Promise<{
+        msg?: string;
+        id?: string;
+    }>;
+    /**
+     * Get the settings of a collection. Requires READ on the collection; the
+     * permissions array is omitted unless the caller is an ADMIN.
+     */
+    get(dataCollectionId: string): Promise<DataCollectionSettings>;
+    /**
+     * Update the settings of a collection. Only set a settings object obtained
+     * through {@link get}. Requires ADMIN on the collection.
+     */
+    update(dataCollectionId: string, settings: DataCollectionSettings): Promise<DataCollectionSettings>;
+    /** Permanently delete a collection. Requires ADMIN on the collection. */
+    delete(dataCollectionId: string): Promise<void>;
+    /** List the objects in a collection. Requires READ on the collection. */
+    listObjects(dataCollectionId: string): Promise<DataCollectionObject[]>;
+    /**
+     * Add an object to a collection. Requires WRITE (Contributor) on the
+     * collection, the mayPublishToDataCollections global group permission, and
+     * publishToDataCollections on the project hosting the object (if relevant).
+     */
+    addObject(dataCollectionId: string, object: DataCollectionObject): Promise<void>;
+    /** Remove a dataset from a collection. Requires WRITE on the collection. */
+    removeDataset(dataCollectionId: string, projectKey: string, datasetName: string): Promise<void>;
+}

package/dist/src/resources/data-collections.js

@@ -0,0 +1,49 @@
+import { BaseResource, } from "./base.js";
+export class DataCollectionsResource extends BaseResource {
+    /** List the collections on which the API key has READ privilege. */
+    async list() {
+        return this.client.get("/public/api/data-collections/");
+    }
+    /**
+     * Create a collection. The creating user is added as an administrator.
+     * Requires the mayCreateDataCollections global permission. DSS returns
+     * `{ msg, id }`; the created id is surfaced to the caller.
+     */
+    async create(body) {
+        return this.client.post("/public/api/data-collections/", body);
+    }
+    /**
+     * Get the settings of a collection. Requires READ on the collection; the
+     * permissions array is omitted unless the caller is an ADMIN.
+     */
+    async get(dataCollectionId) {
+        return this.client.get(`/public/api/data-collections/${encodeURIComponent(dataCollectionId)}`);
+    }
+    /**
+     * Update the settings of a collection. Only set a settings object obtained
+     * through {@link get}. Requires ADMIN on the collection.
+     */
+    async update(dataCollectionId, settings) {
+        return this.client.put(`/public/api/data-collections/${encodeURIComponent(dataCollectionId)}`, settings);
+    }
+    /** Permanently delete a collection. Requires ADMIN on the collection. */
+    async delete(dataCollectionId) {
+        await this.client.del(`/public/api/data-collections/${encodeURIComponent(dataCollectionId)}`);
+    }
+    /** List the objects in a collection. Requires READ on the collection. */
+    async listObjects(dataCollectionId) {
+        return this.client.get(`/public/api/data-collections/${encodeURIComponent(dataCollectionId)}/objects`);
+    }
+    /**
+     * Add an object to a collection. Requires WRITE (Contributor) on the
+     * collection, the mayPublishToDataCollections global group permission, and
+     * publishToDataCollections on the project hosting the object (if relevant).
+     */
+    async addObject(dataCollectionId, object) {
+        await this.client.post(`/public/api/data-collections/${encodeURIComponent(dataCollectionId)}/objects`, object);
+    }
+    /** Remove a dataset from a collection. Requires WRITE on the collection. */
+    async removeDataset(dataCollectionId, projectKey, datasetName) {
+        await this.client.del(`/public/api/data-collections/${encodeURIComponent(dataCollectionId)}/objects/dataset/${encodeURIComponent(projectKey)}/${encodeURIComponent(datasetName)}`);
+    }
+}

package/dist/src/resources/datasets.d.ts

@@ -17,6 +17,37 @@ export interface DatasetSchemaColumnInput {
     type: string;
     comment?: string;
 }
+/** Options for creating a managed dataset through the dedicated endpoint. */
+export interface DatasetManagedCreateOptions {
+    /** Name of the new dataset (unique in the project). */
+    name: string;
+    /** Connection where the dataset is stored. */
+    connection: string;
+    /** When the connection accepts several dataset types, the type to use. */
+    typeOptionId?: string;
+    /** Optional identifier of a file format option (e.g. CSV_EXCEL_GZIP, PARQUET_HIVE). */
+    formatOptionId?: string;
+    /**
+     * Partitioning option id. Use {@link DatasetManagedCreateOptions.copyPartitioningFrom}
+     * to build one from an existing dataset or folder reference.
+     */
+    partitioningOptionId?: string;
+    /**
+     * Copy partitioning from an existing dataset or folder instead of passing a
+     * raw `partitioningOptionId`. `type` defaults to `DATASET` and may be
+     * `FOLDER`.
+     */
+    copyPartitioningFrom?: {
+        ref: string;
+        type?: "DATASET" | "FOLDER";
+    };
+}
+/** Result of creating a managed dataset (the endpoint answers 204 with no body). */
+export interface DatasetManagedCreateResult {
+    datasetName: string;
+    projectKey: string;
+    creationSettings: Record<string, unknown>;
+}
 export interface DatasetCloneOptions {
     projectKey?: string;
     path?: string;
@@ -120,6 +151,44 @@ export declare class DatasetsResource extends BaseResource {
     }>;
     /** Get dataset metadata (tags, custom fields, checklists). */
     metadata(datasetName: string, projectKey?: string): Promise<Record<string, unknown>>;
+    /**
+     * Replace dataset metadata with the given object (faithful PUT per the DSS
+     * API contract: the caller GETs the metadata, edits it, and PUTs the full
+     * object back — no partial merge is applied client-side). `label`,
+     * `description`, `tags`, and `custom` are the documented writable fields;
+     * any additional server-provided metadata fields present in the object are
+     * preserved verbatim.
+     */
+    updateMetadata(datasetName: string, metadata: Record<string, unknown>, projectKey?: string): Promise<Record<string, unknown>>;
+    /**
+     * Create a managed dataset through the dedicated
+     * `POST /projects/{projectKey}/datasets/managed` endpoint. DSS handles the
+     * format/storage details: you select the name, the connection, and optional
+     * type/format/partitioning options. The endpoint answers `204` with no
+     * body; the returned settings echo what was sent.
+     */
+    createManaged(opts: DatasetManagedCreateOptions, projectKey?: string): Promise<DatasetManagedCreateResult>;
+    /**
+     * Get the full info object for a dataset (type, parameters, last build
+     * information, schema, etc.). The server returns a complex opaque object;
+     * it is surfaced without validation.
+     */
+    info(datasetName: string, projectKey?: string): Promise<Record<string, unknown>>;
+    /**
+     * Get the full column lineage (auto-computed and manual) of a column in
+     * this dataset. Relations with datasets from both local and foreign
+     * projects are included.
+     *
+     * Route per the official Python client:
+     * `GET /projects/{projectKey}/datasets/{datasetName}/column-lineage`
+     * with query `columnName` (required) and `maxDatasetCount` (optional,
+     * positive integer — the docs page renders a merged project-scoped path,
+     * but DSS's own client and route registry use this per-dataset form).
+     */
+    getColumnLineage(datasetName: string, column: string, opts?: {
+        maxDatasetCount?: number;
+        projectKey?: string;
+    }): Promise<unknown>;
     /**
      * Download dataset rows as a gzipped (or .csv) file, capped at `limit` rows
      * (default 100k). Returns the written path, the number of data rows written,

package/dist/src/resources/datasets.js

@@ -394,12 +394,39 @@ async function collectTsvRowCount(body, stopAfter, timeoutMs) {
         reader.releaseLock();
     }
 }
+/**
+ * Encoded CSV bytes accumulated before one stream push. Rows are joined into
+ * batch-sized chunks so large downloads do not pay per-row stream overhead; a
+ * single escaped row may exceed the budget (rows are never split), and the
+ * batch is always flushed at EOF so trailing rows are never dropped.
+ */
+const CSV_BATCH_BYTES = 64 * 1024;
 function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true) {
     const state = createTsvStreamState();
     const decoder = new StringDecoder("utf-8");
     const maxRows = Math.max(1, maxDataRows);
     let headerSeen = false;
     let done = false;
+    // Bounded CSV output batching: emitted rows accumulate here and are joined
+    // into a single push once the batch reaches CSV_BATCH_BYTES, so memory stays
+    // bounded by the batch budget plus one escaped row (the join briefly holds a
+    // second copy of the batch) while per-row push/callback overhead disappears.
+    let batchLines = [];
+    let batchBytes = 0;
+    const flushBatch = (target) => {
+        if (batchLines.length === 0)
+            return;
+        const csv = batchLines.join("");
+        batchLines = [];
+        batchBytes = 0;
+        target.push(csv);
+    };
+    const queueLine = (target, line) => {
+        batchLines.push(line);
+        batchBytes += Buffer.byteLength(line);
+        if (batchBytes >= CSV_BATCH_BYTES)
+            flushBatch(target);
+    };
     let columnCount = 0;
     const handleRow = (row, push) => {
         if (done)
@@ -430,7 +457,7 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
                 return;
             }
             try {
-                consumeTsvChunk(decoder.write(chunk), state, (row) => handleRow(row, (line) => this.push(line)));
+                consumeTsvChunk(decoder.write(chunk), state, (row) => handleRow(row, (line) => queueLine(this, line)));
             }
             catch (error) {
                 // Byte-limit overflow: destroy the transform so the pipeline
@@ -438,8 +465,11 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
                 callback(error instanceof Error ? error : new Error(String(error)));
                 return;
             }
-            if (done)
+            if (done) {
+                // Truncation reached: emit the batch queued so far before EOF.
+                flushBatch(this);
                 this.push(null);
+            }
             callback();
         },
         flush(callback) {
@@ -450,14 +480,17 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
             try {
                 const tail = decoder.end();
                 if (tail !== "") {
-                    consumeTsvChunk(tail, state, (row) => handleRow(row, (line) => this.push(line)));
+                    consumeTsvChunk(tail, state, (row) => handleRow(row, (line) => queueLine(this, line)));
                 }
-                flushTsvStream(state, (row) => handleRow(row, (line) => this.push(line)));
+                flushTsvStream(state, (row) => handleRow(row, (line) => queueLine(this, line)));
             }
             catch (error) {
                 callback(error instanceof Error ? error : new Error(String(error)));
                 return;
             }
+            // Emit the trailing partial batch; without this the last rows of a
+            // download (below the batch budget) would be silently dropped.
+            flushBatch(this);
             callback();
         },
     });
@@ -712,6 +745,104 @@ export class DatasetsResource extends BaseResource {
         const dsEnc = encodeURIComponent(datasetName);
         return this.client.get(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/metadata`);
     }
+    /**
+     * Replace dataset metadata with the given object (faithful PUT per the DSS
+     * API contract: the caller GETs the metadata, edits it, and PUTs the full
+     * object back — no partial merge is applied client-side). `label`,
+     * `description`, `tags`, and `custom` are the documented writable fields;
+     * any additional server-provided metadata fields present in the object are
+     * preserved verbatim.
+     */
+    async updateMetadata(datasetName, metadata, projectKey) {
+        if (metadata === null || Array.isArray(metadata)) {
+            throw new ClientValidationError("metadata must be a JSON object.");
+        }
+        const dsEnc = encodeURIComponent(datasetName);
+        return this.client.put(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/metadata`, metadata);
+    }
+    /**
+     * Create a managed dataset through the dedicated
+     * `POST /projects/{projectKey}/datasets/managed` endpoint. DSS handles the
+     * format/storage details: you select the name, the connection, and optional
+     * type/format/partitioning options. The endpoint answers `204` with no
+     * body; the returned settings echo what was sent.
+     */
+    async createManaged(opts, projectKey) {
+        const name = typeof opts.name === "string" ? opts.name.trim() : "";
+        if (name === "") {
+            throw new ClientValidationError("name must be a non-empty dataset name.");
+        }
+        const connection = typeof opts.connection === "string" ? opts.connection.trim() : "";
+        if (connection === "") {
+            throw new ClientValidationError("connection must be a non-empty connection name.");
+        }
+        if (opts.partitioningOptionId !== undefined && opts.copyPartitioningFrom !== undefined) {
+            throw new ClientValidationError("Pass either partitioningOptionId or copyPartitioningFrom, not both.");
+        }
+        if (opts.copyPartitioningFrom !== undefined
+            && (typeof opts.copyPartitioningFrom.ref !== "string"
+                || opts.copyPartitioningFrom.ref.trim() === "")) {
+            throw new ClientValidationError("copyPartitioningFrom.ref must be a non-empty dataset or folder name.");
+        }
+        const pk = this.resolveProjectKey(projectKey);
+        const creationSettings = { connectionId: connection, };
+        if (opts.typeOptionId !== undefined)
+            creationSettings.typeOptionId = opts.typeOptionId;
+        if (opts.formatOptionId !== undefined || opts.partitioningOptionId !== undefined
+            || opts.copyPartitioningFrom !== undefined) {
+            const specificSettings = {};
+            if (opts.formatOptionId !== undefined) {
+                specificSettings.formatOptionId = opts.formatOptionId;
+            }
+            if (opts.partitioningOptionId !== undefined) {
+                specificSettings.partitioningOptionId = opts.partitioningOptionId;
+            }
+            else if (opts.copyPartitioningFrom !== undefined) {
+                const code = opts.copyPartitioningFrom.type === "FOLDER" ? "folder" : "dataset";
+                specificSettings.partitioningOptionId = `copy:${code}:${opts.copyPartitioningFrom.ref.trim()}`;
+            }
+            creationSettings.specificSettings = specificSettings;
+        }
+        await this.client.post(`/public/api/projects/${encodeURIComponent(pk)}/datasets/managed`, { name, creationSettings, });
+        return { datasetName: name, projectKey: pk, creationSettings, };
+    }
+    /**
+     * Get the full info object for a dataset (type, parameters, last build
+     * information, schema, etc.). The server returns a complex opaque object;
+     * it is surfaced without validation.
+     */
+    async info(datasetName, projectKey) {
+        const dsEnc = encodeURIComponent(datasetName);
+        return this.client.get(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/info`);
+    }
+    /**
+     * Get the full column lineage (auto-computed and manual) of a column in
+     * this dataset. Relations with datasets from both local and foreign
+     * projects are included.
+     *
+     * Route per the official Python client:
+     * `GET /projects/{projectKey}/datasets/{datasetName}/column-lineage`
+     * with query `columnName` (required) and `maxDatasetCount` (optional,
+     * positive integer — the docs page renders a merged project-scoped path,
+     * but DSS's own client and route registry use this per-dataset form).
+     */
+    async getColumnLineage(datasetName, column, opts = {}) {
+        const trimmed = typeof column === "string" ? column.trim() : "";
+        if (trimmed === "") {
+            throw new ClientValidationError("column must be a non-empty column name.");
+        }
+        const maxDatasetCount = opts.maxDatasetCount;
+        if (maxDatasetCount !== undefined
+            && (!Number.isSafeInteger(maxDatasetCount) || maxDatasetCount <= 0)) {
+            throw new ClientValidationError("maxDatasetCount must be a positive integer.");
+        }
+        const dsEnc = encodeURIComponent(datasetName);
+        const params = [`columnName=${encodeURIComponent(trimmed)}`,];
+        if (maxDatasetCount !== undefined) {
+            params.push(`maxDatasetCount=${encodeURIComponent(String(maxDatasetCount))}`);
+        }
+        return this.client.get(`/public/api/projects/${this.enc(opts?.projectKey)}/datasets/${dsEnc}/column-lineage?${params.join("&")}`);
+    }
     /**
      * Download dataset rows as a gzipped (or .csv) file, capped at `limit` rows
      * (default 100k). Returns the written path, the number of data rows written,
@@ -746,7 +877,7 @@ export class DatasetsResource extends BaseResource {
             : undefined;
         const shouldGzip = filePath.endsWith(".gz");
         const stats = { rows: 0, truncated: false, };
-        const nodeStream = Readable.fromWeb(res.body);
+        const nodeStream = Readable.from(res.body, { objectMode: false, });
         const csvTransform = tsvToCsvTransform(limit, stats, onHeader, opts?.rawData !== true);
         fs.mkdirSync(nodePath.dirname(filePath), { recursive: true, });
         const fileOut = fs.createWriteStream(filePath);

package/dist/src/resources/flow-zones.d.ts

@@ -1,3 +1,4 @@
+import type { DataikuGetOptions } from "../client.js";
 import type { FlowZone, FlowZoneCreateOptions, FlowZoneObjectType, FlowZoneUpdateOptions } from "../schemas.js";
 import { BaseResource } from "./base.js";
 export type FlowZoneItemInput = {
@@ -6,8 +7,11 @@ export type FlowZoneItemInput = {
     projectKey?: string;
 };
 export declare class FlowZonesResource extends BaseResource {
-    /** List all flow zones in a project. */
-    list(projectKey?: string): Promise<FlowZone[]>;
+    /**
+     * List all flow zones in a project. Pass `timeoutMs` to bound the whole
+     * request (attempts, backoff, and body read) by a total budget.
+     */
+    list(projectKey?: string, options?: DataikuGetOptions): Promise<FlowZone[]>;
     /** Get one flow zone by id. */
     get(zoneId: string, projectKey?: string): Promise<FlowZone>;
     /** Create a flow zone. */

package/dist/src/resources/flow-zones.js

@@ -9,9 +9,12 @@ function normalizeZoneItem(item) {
     };
 }
 export class FlowZonesResource extends BaseResource {
-    /** List all flow zones in a project. */
-    async list(projectKey) {
-        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/flow/zones`);
+    /**
+     * List all flow zones in a project. Pass `timeoutMs` to bound the whole
+     * request (attempts, backoff, and body read) by a total budget.
+     */
+    async list(projectKey, options) {
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/flow/zones`, options);
         return this.client.safeParse(FlowZoneArraySchema, raw, "flowZones.list");
     }
     /** Get one flow zone by id. */

package/dist/src/resources/futures.d.ts

@@ -5,10 +5,15 @@ export interface FutureWaitOptions {
     timeoutMs?: number;
 }
 export declare class FuturesResource extends BaseResource {
-    get(futureId: string): Promise<FutureState>;
+    get(futureId: string, opts?: {
+        timeoutMs?: number;
+        noRetry?: boolean;
+    }): Promise<FutureState>;
     peek(futureId: string): Promise<FutureState>;
     state(futureId: string, opts?: {
         peek?: boolean;
+        timeoutMs?: number;
+        noRetry?: boolean;
     }): Promise<FutureState>;
     abort(futureId: string): Promise<void>;
     wait(futureId: string, opts?: FutureWaitOptions): Promise<FutureWaitResult>;

package/dist/src/resources/futures.js

@@ -1,4 +1,5 @@
 import { FutureStateSchema, FutureWaitResultSchema, } from "../schemas.js";
+import { computeNextPollDelayMs, isRequestDeadlineError, } from "../utils/polling.js";
 import { BaseResource, } from "./base.js";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -23,8 +24,12 @@ function waitState(state) {
     return "RUNNING";
 }
 export class FuturesResource extends BaseResource {
-    async get(futureId) {
-        return this.state(futureId, { peek: false, });
+    async get(futureId, opts = {}) {
+        return this.state(futureId, {
+            peek: false,
+            timeoutMs: opts.timeoutMs,
+            noRetry: opts.noRetry,
+        });
     }
     async peek(futureId) {
         return this.state(futureId, { peek: true, });
@@ -32,23 +37,71 @@ export class FuturesResource extends BaseResource {
     async state(futureId, opts = {}) {
         const params = new URLSearchParams();
         params.set("peek", String(opts.peek === true));
-        const raw = await this.client.get(`/public/api/futures/${encodeURIComponent(futureId)}?${params.toString()}`);
+        const raw = await this.client.get(`/public/api/futures/${encodeURIComponent(futureId)}?${params.toString()}`, { timeoutMs: opts.timeoutMs, noRetry: opts.noRetry, });
         return this.client.safeParse(FutureStateSchema, raw, "futures.state");
     }
     async abort(futureId) {
         await this.client.del(`/public/api/futures/${encodeURIComponent(futureId)}`);
     }
     async wait(futureId, opts = {}) {
-        const baseIntervalMs = Math.max(1, opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+        // Adaptive backoff is the default; an explicit pollIntervalMs is an
+        // exact contract the caller chose, so it is never adapted.
+        const explicitIntervalMs = opts.pollIntervalMs;
+        const baseIntervalMs = Math.max(1, explicitIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+        const adaptiveEnabled = explicitIntervalMs === undefined;
         // A caller's budget is never rounded up to a whole poll interval: a 5ms
         // wait must answer in about 5ms. One state observation always happens
         // regardless, because the poll precedes the deadline check.
         const timeoutMs = Math.max(0, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
         const startedAt = Date.now();
         let pollCount = 0;
+        let lastState;
         while (true) {
+            const elapsedBeforeMs = Date.now() - startedAt;
+            // The first observation always happens, even when the budget is
+            // already spent. A later poll is never started after the deadline:
+            // the loop reports the structured timeout from the last observed
+            // state instead of issuing a request the budget cannot cover.
+            if (lastState !== undefined && elapsedBeforeMs >= timeoutMs) {
+                return this.client.safeParse(FutureWaitResultSchema, {
+                    futureId,
+                    jobId: lastState.jobId,
+                    state: waitState(lastState),
+                    elapsedMs: elapsedBeforeMs,
+                    pollCount,
+                    success: false,
+                    timedOut: true,
+                    hasResult: lastState.hasResult === true,
+                    alive: lastState.alive,
+                    aborted: lastState.aborted,
+                    unknown: lastState.unknown,
+                }, "futures.wait");
+            }
             pollCount += 1;
-            const state = await this.get(futureId);
+            // Requests issued while budget remains are bounded by the remaining
+            // time; a spent budget still issues exactly one transport attempt
+            // (no retries, client requestTimeoutMs cap) so the first observation
+            // reaches the server instead of failing before any attempt.
+            const remainingMs = timeoutMs - elapsedBeforeMs;
+            let state;
+            try {
+                state = await this.get(futureId, remainingMs > 0 ? { timeoutMs: remainingMs, } : { noRetry: true, });
+            }
+            catch (error) {
+                // The poll budget ran out mid-request: report the structured
+                // timeout instead of letting the transport deadline error escape.
+                if (!isRequestDeadlineError(error, startedAt + timeoutMs))
+                    throw error;
+                return this.client.safeParse(FutureWaitResultSchema, {
+                    futureId,
+                    state: "RUNNING",
+                    elapsedMs: Date.now() - startedAt,
+                    pollCount,
+                    success: false,
+                    timedOut: true,
+                }, "futures.wait");
+            }
+            lastState = state;
             const elapsedMs = Date.now() - startedAt;
             const status = waitState(state);
             if (isFinished(state)) {
@@ -67,25 +120,18 @@ export class FuturesResource extends BaseResource {
                 };
                 return this.client.safeParse(FutureWaitResultSchema, result, "futures.wait");
             }
-            if (elapsedMs >= timeoutMs) {
-                const result = {
-                    futureId,
-                    jobId: state.jobId,
-                    state: status,
-                    elapsedMs,
-                    pollCount,
-                    success: false,
-                    timedOut: true,
-                    hasResult: state.hasResult === true,
-                    alive: state.alive,
-                    aborted: state.aborted,
-                    unknown: state.unknown,
-                };
-                return this.client.safeParse(FutureWaitResultSchema, result, "futures.wait");
-            }
+            // Deadline reached: the guard at the top of the loop reports the
+            // timeout from this observation without issuing another request.
+            if (elapsedMs >= timeoutMs)
+                continue;
             // Only the remaining budget is slept: a longer sleep would report an
             // elapsed time the caller never authorized.
-            await sleep(Math.min(baseIntervalMs, timeoutMs - elapsedMs));
+            const nextDelayMs = computeNextPollDelayMs({
+                pollCount,
+                baseIntervalMs,
+                adaptiveEnabled,
+            });
+            await sleep(Math.min(nextDelayMs, timeoutMs - elapsedMs));
         }
     }
 }