dataiku-sdk 3.3.0 → 3.5.0

package/dist/src/cli/usage.d.ts

@@ -1,6 +1,6 @@
 import type { StableErrorCode } from "../errors.js";
 export declare const RESOURCE_NAMES: string[];
-export declare function inferRequiresProject(resource: string, action: string, usage: string): boolean;
+export declare function inferRequiresProject(resource: string, action: string): boolean;
 export declare class UsageError extends Error {
     readonly code: StableErrorCode;
     readonly hint?: string;

package/dist/src/cli/usage.js

@@ -1,3 +1,4 @@
+import { commandSyntaxTree, syntaxHasFlag, } from "./syntax.js";
 export const RESOURCE_NAMES = [
     "agent",
     "app",
@@ -79,7 +80,7 @@ const PROJECT_SCOPED_RESOURCES = new Set([
     "saved-model",
     "wiki",
 ]);
-export function inferRequiresProject(resource, action, usage) {
+export function inferRequiresProject(resource, action) {
     if (resource === "agent" || resource === "auth" || resource === "doctor" || resource === "commands"
         || resource === "install-skill" || resource === "version")
         return false;
@@ -92,7 +93,8 @@ export function inferRequiresProject(resource, action, usage) {
         return false;
     if (resource === "project-git")
         return !action.startsWith("future-");
-    return usage.includes("--project-key");
+    const syntax = commandSyntaxTree(resource, action);
+    return syntax !== undefined && syntaxHasFlag(syntax, "project-key");
 }
 export class UsageError extends Error {
     code;

package/dist/src/cli/version.js

@@ -212,8 +212,10 @@ export const AGENT_CONTRACT_VERSION = 2;
 export const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v2.json";
 export function cliVersionResult() {
+    /* oxlint-disable dss/no-direct-process-env -- launcher-injected load source and build revision */
     const loadSource = process.env["DSS_LOAD_SOURCE"] ?? detectLoadSource();
     const envBuildRevision = process.env["DSS_BUILD_REVISION"];
+    /* oxlint-enable dss/no-direct-process-env */
     return buildVersionPayload({
         packageVersion: CLI_VERSION,
         checkoutRevision: CLI_GIT_REVISION,

package/dist/src/cli.js

@@ -4,7 +4,7 @@ import { homedir, } from "node:os";
 import { resolve, } from "node:path";
 import { num, unknownJsonInput, } from "./cli/coerce.js";
 import { commands, } from "./cli/commands/index.js";
-import { dataikuEnvironmentEnabled, loadEnvFile, } from "./cli/env.js";
+import { ambientProjectKey, loadEnvFile, } from "./cli/env.js";
 import { executionMode, FLAG_ALIASES, isNegativeNumberToken, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
 import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
 import { commandFailureExitCode, CommandResultFailure, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
@@ -334,32 +334,11 @@ function validateSupportedCommandFlags(resource, action, flags) {
             ? "Remove --dry-run; use --plan to preview the mutation instead."
             : `Remove --dry-run; ${resource} ${action} has no dry-run mode.`);
     }
-}
-function stripOptionalUsageGroupsForValidation(usage) {
-    let stripped = "";
-    let optionalDepth = 0;
-    for (const char of usage) {
-        if (char === "[") {
-            optionalDepth++;
-            if (optionalDepth === 1)
-                stripped += " ";
-            continue;
-        }
-        if (char === "]" && optionalDepth > 0) {
-            optionalDepth--;
-            if (optionalDepth === 0)
-                stripped += " ";
-            continue;
-        }
-        if (optionalDepth === 0)
-            stripped += char;
+    // Registry commands reject --plan in buildMutationPlan; meta commands never reach it.
+    if (META_COMMAND_RESOURCES[resource] === true && executionMode(flags).plan
+        && !entry.flags.some((flag) => flag.name === "plan")) {
+        throw new UsageError(`--plan is only supported for mutating commands; ${resource} ${action} has no plan mode.`, "usage_error", `Remove --plan; ${resource} ${action} has no plan mode.`);
     }
-    return stripped;
-}
-function requiredPositionalCount(usage) {
-    const requiredUsage = stripOptionalUsageGroupsForValidation(usage);
-    const positionalTokens = [...requiredUsage.matchAll(/<[^>]+>/g),];
-    return positionalTokens.length;
 }
 function flagIsProvided(flags, name, allowEmpty = false) {
     const value = flags[name];
@@ -370,7 +349,7 @@ function flagIsProvided(flags, name, allowEmpty = false) {
     return allowEmpty || value.length > 0;
 }
 function validateRequiredCommandInputs(resource, action, args, flags, entry) {
-    const argCount = requiredPositionalCount(entry.usage);
+    const argCount = entry.positionalArguments.filter((positional) => positional.required).length;
     const allowEmptyFlags = {};
     for (const flag of entry.flags) {
         if (flag.allowEmptyValue === true)
@@ -776,6 +755,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("doctor", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("doctor", "run", flags);
         const { runDoctor, } = await import("./cli/doctor.js");
         const { result, exitCode, } = await runDoctor(flags);
         return { action: "run", result, exitCode, };
@@ -791,6 +771,7 @@ async function runMetaCommand(resource, action, flags) {
         if (!authMeta) {
             throw unknownActionError("auth", action, validActions, "auth only supports 'login'. To check credentials/connectivity, run 'dss doctor'.");
         }
+        validateSupportedCommandFlags("auth", action, flags);
         if (executionMode(flags).plan) {
             return { action, result: authLoginPlan(flags), exitCode: 0, };
         }
@@ -802,6 +783,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("install-skill", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("install-skill", "run", flags);
         return { action: "run", result: await runInstallSkill(flags), exitCode: 0, };
     }
     if (resource === "agent") {
@@ -811,6 +793,7 @@ async function runMetaCommand(resource, action, flags) {
         currentCommandContext.action = action;
         if (action !== "contract")
             throw unknownActionError("agent", action, ["contract",]);
+        validateSupportedCommandFlags("agent", "contract", flags);
         return { action, result: contract.buildAgentContract(), exitCode: 0, };
     }
     if (resource === "commands") {
@@ -856,10 +839,12 @@ async function runMetaCommand(resource, action, flags) {
         };
     }
     if (resource === "version") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             throw unknownActionError("version", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("version", "run", flags);
         return { action: "run", result: cliVersionResult(), exitCode: 0, };
     }
     if (resource === "cleanup") {
@@ -868,6 +853,10 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("cleanup", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("cleanup", "run", flags);
+        if (flags["apply"] === true && executionMode(flags).dryRun) {
+            throw new UsageError("--dry-run and --apply are mutually exclusive.", "usage_error");
+        }
         if (executionMode(flags).plan) {
             return { action: "run", result: cleanupPlan(flags), exitCode: 0, };
         }
@@ -880,6 +869,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("fixtures", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("fixtures", "run", flags);
         const { runFixtures, } = await import("./cli/doctor.js");
         return { action: "run", result: await runFixtures(flags), exitCode: 0, };
     }
@@ -889,6 +879,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("batch", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        validateSupportedCommandFlags("batch", "run", flags);
         if (executionMode(flags).plan) {
             return { action: "run", result: batchPlan(flags), exitCode: 0, };
         }
@@ -993,9 +984,7 @@ async function runBatch(flags) {
     if (executionMode(flags).dryRun) {
         const batchProjectKey = typeof flags["project-key"] === "string"
             ? flags["project-key"]
-            : dataikuEnvironmentEnabled()
-                ? process.env.DATAIKU_PROJECT_KEY
-                : undefined;
+            : ambientProjectKey();
         const planned = await Promise.all(steps.map(async (argv, index) => {
             const context = batchStepCommandContext(argv);
             Object.assign(currentCommandContext, { ...context, projectKey: batchProjectKey, });
@@ -1018,7 +1007,8 @@ async function runBatch(flags) {
                 };
             }
             catch (error) {
-                const envelope = buildErrorReport(error);
+                // Steps validate concurrently; the shared context may belong to a sibling.
+                const envelope = buildErrorReport(error, { ...context, projectKey: batchProjectKey, });
                 return {
                     index,
                     args: redactArgv(argv),
@@ -1037,9 +1027,7 @@ async function runBatch(flags) {
     validateBatchStepModes(steps);
     let projectKey = typeof flags["project-key"] === "string"
         ? flags["project-key"]
-        : dataikuEnvironmentEnabled()
-            ? process.env.DATAIKU_PROJECT_KEY
-            : undefined;
+        : ambientProjectKey();
     let client;
     const needsClient = steps.some((argv) => batchStepNeedsClient(argv));
     if (needsClient) {
@@ -1247,8 +1235,7 @@ function rawFlagValue(argv, flagName) {
 function commandIsProjectScoped(resource, action) {
     if (!resource)
         return false;
-    const usage = commands[resource]?.[action ?? ""]?.usage ?? "";
-    return inferRequiresProject(resource, action ?? "", usage);
+    return inferRequiresProject(resource, action ?? "");
 }
 function rawCommandContext() {
     const argv = process.argv.slice(2);
@@ -1256,15 +1243,13 @@ function rawCommandContext() {
     const resource = currentCommandContext.resource ?? positionals[0];
     const action = currentCommandContext.action ?? positionals[1];
     const explicitProjectKey = rawFlagValue(argv, "project-key") ?? rawFlagValue(argv, "project");
-    const ambientProjectKey = dataikuEnvironmentEnabled()
-        ? process.env.DATAIKU_PROJECT_KEY
-        : undefined;
+    const environmentProjectKey = ambientProjectKey();
     return {
         resource,
         action,
         projectKey: explicitProjectKey
             ?? (commandIsProjectScoped(resource, action)
-                ? currentCommandContext.projectKey ?? ambientProjectKey
+                ? currentCommandContext.projectKey ?? environmentProjectKey
                 : undefined),
     };
 }
@@ -1364,7 +1349,6 @@ function dssDiagnosticDetails(err) {
         return {};
     }
 }
-const MISSING_PROJECT_KEY_ERROR_PREFIX = "projectKey is required";
 function isAmbiguousMutationFailure(err, context) {
     if (!(err instanceof DataikuError))
         return false;
@@ -1399,9 +1383,11 @@ function boundedFailureResult(result) {
 function errorExitCode(err) {
     if (err instanceof CommandResultFailure)
         return err.exitCode;
-    if (err instanceof ClientValidationError && err.code === "assertion_failed")
+    if (err instanceof ClientValidationError
+        && (err.code === "assertion_failed" || err.code === "long_running_failure"))
         return 4;
-    if (err instanceof ClientValidationError && err.code === "ambiguous_outcome")
+    if (err instanceof ClientValidationError
+        && (err.code === "ambiguous_outcome" || err.code === "internal_error"))
         return 2;
     if (err instanceof UsageError || err instanceof ClientValidationError)
         return 1;
@@ -1409,15 +1395,14 @@ function errorExitCode(err) {
         return 2;
     if (err instanceof DataikuError)
         return err.category === "transient" ? 3 : 2;
-    if (err instanceof Error && err.message.startsWith(MISSING_PROJECT_KEY_ERROR_PREFIX))
-        return 1;
     return 2;
 }
-function buildErrorReport(err) {
-    const context = rawCommandContext();
+function buildErrorReport(err, contextOverride) {
+    const context = contextOverride ?? rawCommandContext();
     const exitCode = errorExitCode(err);
     if (err instanceof ClientValidationError
-        && (err.code === "ambiguous_outcome" || err.code === "assertion_failed")) {
+        && (err.code === "ambiguous_outcome" || err.code === "assertion_failed"
+            || err.code === "long_running_failure")) {
         return {
             type: "error",
             ok: false,
@@ -1439,7 +1424,9 @@ function buildErrorReport(err) {
             code: err.code,
             category: err.code === "target_absence_unverifiable"
                 ? "permission_or_environment"
-                : "usage",
+                : err.code === "internal_error"
+                    ? "internal"
+                    : "usage",
             exitCode,
             ...(err.code === "target_absence_unverifiable" ? { retryable: false, } : {}),
             ...(err.hint ? { hint: err.hint, } : {}),
@@ -1517,18 +1504,6 @@ function buildErrorReport(err) {
             ...context,
         };
     }
-    if (err instanceof Error && err.message.startsWith(MISSING_PROJECT_KEY_ERROR_PREFIX)) {
-        return {
-            type: "error",
-            ok: false,
-            error: err.message,
-            code: "missing_required_flag",
-            category: "usage",
-            exitCode,
-            hint: "Pass --project-key or set DATAIKU_PROJECT_KEY.",
-            ...context,
-        };
-    }
     const message = err instanceof Error ? err.message : String(err);
     return {
         type: "error",
@@ -1579,9 +1554,7 @@ async function main() {
         action: positional[1],
         projectKey: typeof flags["project-key"] === "string"
             ? flags["project-key"]
-            : dataikuEnvironmentEnabled()
-                ? process.env.DATAIKU_PROJECT_KEY
-                : undefined,
+            : ambientProjectKey(),
     });
     const metaCommand = await runMetaCommand(resource, positional[1], flags);
     if (metaCommand) {

package/dist/src/client.d.ts

@@ -73,6 +73,15 @@ export interface DataikuGetOptions {
      * budget may shorten those limits but never extends them.
      */
     timeoutMs?: number;
+    /**
+     * Issue exactly one transport attempt (no retries). Independent of
+     * `timeoutMs`: when both are supplied the total budget above still applies
+     * and aborts the attempt; when no budget is supplied the attempt is capped
+     * by the client-level `requestTimeoutMs`. Wait loops use this for the one
+     * observation whose wait budget is already spent, so it still reaches the
+     * server once instead of failing before any transport attempt.
+     */
+    noRetry?: boolean;
 }
 export interface DataikuClientTraceEvent {
     type: "trace";
@@ -298,7 +307,7 @@ export declare class DataikuClient {
     /** Send raw file contents through the shared authenticated transport. */
     postRawBody(path: string, body: string | Uint8Array): Promise<void>;
     /** Git endpoints require Basic API-key authentication, unlike the bearer API. */
-    requestGit(method: string, path: string, body?: unknown, deadlineAt?: number): Promise<Response>;
+    requestGit(method: string, path: string, body?: unknown, deadlineAt?: number, noRetry?: boolean): Promise<Response>;
     postStream(path: string, body?: unknown): Promise<Response>;
     put<T = unknown>(path: string, body: unknown): Promise<T>;
     del(path: string): Promise<void>;

package/dist/src/client.js

@@ -3,7 +3,7 @@ import { basename, } from "node:path";
 import { getCACertificates, } from "node:tls";
 import { Value, } from "@sinclair/typebox/value";
 import { safeParseSchema, } from "./schemas.js";
-import { classifyDataikuError, ClientValidationError, DataikuError, NON_JSON_RESPONSE_MARKER, } from "./errors.js";
+import { classifyDataikuError, ClientValidationError, DataikuError, nonJsonResponseBody, } from "./errors.js";
 import { AnalysesResource, } from "./resources/analyses.js";
 import { ApiDeployerResource, } from "./resources/api-deployer.js";
 import { ApiServicesResource, } from "./resources/api-services.js";
@@ -78,6 +78,19 @@ function computeBackoffDelayMs(retryNumber) {
     const cap = Math.min(MAX_BACKOFF_DELAY_MS, BASE_DELAY_MS * 2 ** Math.max(0, retryNumber - 1));
     return Math.floor(Math.random() * (cap + 1));
 }
+/** Server-directed waits never bypass the existing automatic backoff cap. */
+function retryAfterDelayMs(value) {
+    if (value === null)
+        return 0;
+    const text = value.trim();
+    if (/^\d+$/.test(text))
+        return Number(text) * 1_000;
+    // Accept HTTP dates, not Date.parse's permissive numeric date shorthand.
+    if (!/^[A-Za-z]{3,9},? /.test(text))
+        return 0;
+    const date = Date.parse(text);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+}
 function isTransientError(status, body) {
     return classifyDataikuError(status, body).category === "transient";
 }
@@ -174,7 +187,7 @@ function buildFetchTlsOptions(config) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Unable to read CA certificate bundle at ${caCertPath}: ${message}`, {
+            throw new ClientValidationError(`Unable to read CA certificate bundle at ${caCertPath}: ${message}`, "invalid_flag_value", undefined, undefined, {
                 cause: error,
             });
         }
@@ -403,12 +416,14 @@ export class DataikuClient {
         return (this.groupsResource ??= new GroupsResource(this));
     }
     constructor(config) {
+        /* oxlint-disable dss/no-direct-process-env -- SDK constructor defaults (DATAIKU_URL/DATAIKU_API_KEY) for library callers */
         const envUrl = process.env["DATAIKU_URL"]?.trim();
         const envApiKey = process.env["DATAIKU_API_KEY"]?.trim();
+        /* oxlint-enable dss/no-direct-process-env */
         const url = config?.url?.trim() || envUrl;
         const apiKey = config?.apiKey?.trim() || envApiKey;
         if (!url || !apiKey) {
-            throw new Error("Dataiku URL and API key are required: pass {url, apiKey} or set DATAIKU_URL/DATAIKU_API_KEY");
+            throw new ClientValidationError("Dataiku URL and API key are required: pass {url, apiKey} or set DATAIKU_URL/DATAIKU_API_KEY", "missing_required_flag");
         }
         if (hasEmbeddedUserinfo(url)) {
             throw new ClientValidationError("Dataiku URL must not contain embedded credentials (userinfo). Authenticate with an API key instead.", "validation_failed", "Pass the DSS base URL without a username or password.", { urlHasEmbeddedUserinfo: true, });
@@ -450,12 +465,12 @@ export class DataikuClient {
             return pk;
         if (this.defaultProjectKey)
             return this.defaultProjectKey;
-        throw new Error("projectKey is required — pass it as a parameter or set projectKey in DataikuClientConfig");
+        throw new ClientValidationError("projectKey is required — pass it as a parameter or set projectKey in DataikuClientConfig", "missing_required_flag", "Pass --project-key or set DATAIKU_PROJECT_KEY.");
     }
     /* ---- public: HTTP verbs ---- */
     async get(path, options) {
         const deadlineAt = resolveGetDeadlineAt(options);
-        const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, { method: "GET", headers: this.getHeaders(), }, undefined, deadlineAt);
+        const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, { method: "GET", headers: this.getHeaders(), }, options?.noRetry === true ? 1 : undefined, deadlineAt);
         return this.parseJsonResponse(res, deadlineAt);
     }
     /**
@@ -563,7 +578,7 @@ export class DataikuClient {
         await response.text();
     }
     /** Git endpoints require Basic API-key authentication, unlike the bearer API. */
-    async requestGit(method, path, body, deadlineAt) {
+    async requestGit(method, path, body, deadlineAt, noRetry = false) {
         return this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method,
             headers: {
@@ -572,7 +587,7 @@ export class DataikuClient {
                 "Content-Type": "application/json",
             },
             body: body === undefined ? undefined : JSON.stringify(body),
-        }, undefined, deadlineAt);
+        }, noRetry ? 1 : undefined, deadlineAt);
     }
     async postStream(path, body) {
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
@@ -797,8 +812,7 @@ export class DataikuClient {
             return JSON.parse(text);
         }
         catch {
-            const summary = text.length > 300 ? `${text.slice(0, 300)}…` : text;
-            throw new DataikuError(res.status, res.statusText || "Invalid JSON response", `${NON_JSON_RESPONSE_MARKER}: ${summary}`, undefined, this.requestIdFromHeaders(res.headers));
+            throw new DataikuError(res.status, res.statusText || "Invalid JSON response", nonJsonResponseBody(text), undefined, this.requestIdFromHeaders(res.headers));
         }
     }
     /* ---- private: bounded response body reading ---- */
@@ -1018,8 +1032,10 @@ export class DataikuClient {
                 if (!res.ok) {
                     const { text, truncated, } = await this.readBoundedBodyText(res, this.maxResponseBodyBytes, startedAt + attemptTimeoutMs);
                     const canRetry = retryEnabled && attempt < maxAttempts && isTransientError(res.status, text);
-                    if (canRetry) {
-                        const delayMs = computeBackoffDelayMs(attempt);
+                    const serverDelayMs = canRetry ? retryAfterDelayMs(res.headers.get("retry-after")) : 0;
+                    // A longer server wait declines automatic retry; never clamp it into an early request.
+                    if (canRetry && serverDelayMs <= MAX_BACKOFF_DELAY_MS) {
+                        const delayMs = Math.max(computeBackoffDelayMs(attempt), serverDelayMs);
                         // Do not start a retry whose backoff cannot fit in the budget.
                         if (deadlineAt === undefined || Date.now() + delayMs <= deadlineAt) {
                             delaysMs.push(delayMs);

package/dist/src/errors.d.ts

@@ -26,7 +26,7 @@ export declare class ClientValidationError extends Error {
     readonly code: StableErrorCode;
     readonly hint?: string;
     readonly details?: Record<string, unknown>;
-    constructor(message: string, code?: StableErrorCode, hint?: string, details?: Record<string, unknown>);
+    constructor(message: string, code?: StableErrorCode, hint?: string, details?: Record<string, unknown>, options?: ErrorOptions);
 }
 /**
  * Message prefix the client stamps on a 2xx body that is not JSON. The
@@ -34,6 +34,17 @@ export declare class ClientValidationError extends Error {
  * taxonomy stay in sync as one contract.
  */
 export declare const NON_JSON_RESPONSE_MARKER = "Expected JSON response body but got non-JSON content";
+/** Body text for a 2xx response that should have been JSON; truncated to keep envelopes bounded. */
+export declare function nonJsonResponseBody(text: string): string;
+/** Prefix for a 2xx DSS response that lacks something the API documents (a body, an id, a job id). */
+export declare const UNEXPECTED_RESPONSE_MARKER = "Unexpected DSS response";
+/**
+ * The one representation of a malformed 2xx DSS response: a DataikuError whose
+ * body carries {@link UNEXPECTED_RESPONSE_MARKER}, classified `unexpected_response`.
+ */
+export declare function unexpectedResponseError(detail: string, status?: number): DataikuError;
+/** Prefix for a SQL query failure reported by DSS on a 2xx finish-streaming response. */
+export declare const SQL_QUERY_FAILED_MARKER = "SQL query failed in DSS";
 export declare function classifyDataikuError(status: number, body: string): DataikuErrorTaxonomy;
 export declare class DataikuError extends Error {
     status: number;

package/dist/src/errors.js

@@ -47,8 +47,8 @@ export class ClientValidationError extends Error {
     code;
     hint;
     details;
-    constructor(message, code = "validation_failed", hint, details) {
-        super(message);
+    constructor(message, code = "validation_failed", hint, details, options) {
+        super(message, options);
         this.name = "ClientValidationError";
         this.code = code;
         this.hint = hint;
@@ -61,6 +61,21 @@ export class ClientValidationError extends Error {
  * taxonomy stay in sync as one contract.
  */
 export const NON_JSON_RESPONSE_MARKER = "Expected JSON response body but got non-JSON content";
+/** Body text for a 2xx response that should have been JSON; truncated to keep envelopes bounded. */
+export function nonJsonResponseBody(text) {
+    return `${NON_JSON_RESPONSE_MARKER}: ${text.length > 300 ? `${text.slice(0, 300)}…` : text}`;
+}
+/** Prefix for a 2xx DSS response that lacks something the API documents (a body, an id, a job id). */
+export const UNEXPECTED_RESPONSE_MARKER = "Unexpected DSS response";
+/**
+ * The one representation of a malformed 2xx DSS response: a DataikuError whose
+ * body carries {@link UNEXPECTED_RESPONSE_MARKER}, classified `unexpected_response`.
+ */
+export function unexpectedResponseError(detail, status = 200) {
+    return new DataikuError(status, "Unexpected Response", `${UNEXPECTED_RESPONSE_MARKER}: ${detail}`);
+}
+/** Prefix for a SQL query failure reported by DSS on a 2xx finish-streaming response. */
+export const SQL_QUERY_FAILED_MARKER = "SQL query failed in DSS";
 const TLS_CERTIFICATE_HINT = "TLS certificate verification failed. Trust the DSS/corporate CA with --ca-cert PATH or NODE_EXTRA_CA_CERTS; use --insecure only for temporary troubleshooting.";
 const BUSINESS_APPS_API_UNAVAILABLE_HINT = "Business Apps API is not available on this DSS instance. Use classic app commands or check DSS version/feature availability.";
 const MAX_ERROR_SUMMARY_LENGTH = 200;
@@ -92,10 +107,12 @@ function firstHtmlTextLine(body) {
         .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ")
         .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ")
         .replace(/<[^>]+>/g, "\n"));
-    return text
-        .split(/\r?\n/g)
-        .map((line) => line.trim())
-        .find((line) => line.length > 0);
+    for (const match of text.matchAll(/[^\n]+/g)) {
+        const line = match[0].trim();
+        if (line.length > 0)
+            return line;
+    }
+    return undefined;
 }
 function conciseErrorSummary(text) {
     const sanitized = stripServerFilesystemPaths(text);
@@ -164,13 +181,23 @@ export function classifyDataikuError(status, body) {
     // login page, HTML gateway) answered in place of the DSS API. Only the client's
     // own parse-failure marker produces this prefix.
     if (status >= 200 && status < 300
-        && lowerBody.startsWith(NON_JSON_RESPONSE_MARKER.toLowerCase())) {
+        && (lowerBody.startsWith(NON_JSON_RESPONSE_MARKER.toLowerCase())
+            || lowerBody.startsWith(UNEXPECTED_RESPONSE_MARKER.toLowerCase()))) {
         return {
             category: "unexpected_response",
             retryable: false,
             retryHint: "DSS returned a non-JSON response to a JSON API request (typically a proxy, gateway, or login page). Verify the DSS URL and that no intermediary serves HTML; do not retry unchanged.",
         };
     }
+    // finish-streaming answers 2xx with the server-side failure text when the
+    // query itself failed (bad SQL, missing column, permissions on the source).
+    if (status >= 200 && status < 300 && lowerBody.startsWith(SQL_QUERY_FAILED_MARKER.toLowerCase())) {
+        return {
+            category: "validation",
+            retryable: false,
+            retryHint: "The SQL query failed in DSS. Fix the query or its inputs; do not retry unchanged.",
+        };
+    }
     const isSqlInputConnectionMismatch = (status === 400 || status >= 500)
         && lowerBody.includes("s3 dataset")
         && lowerBody.includes("athena connection");