dataiku-sdk 3.9.0 → 4.0.0

package/dist/src/cli/contract.js

@@ -248,6 +248,13 @@ const ALLOWED_CLEANUP_ACTIONS = new Set([
     "project-library delete",
     "streaming-endpoint delete",
     "workspace delete",
+    "saved-model delete",
+    "project-folder delete",
+    "data-collection delete",
+    "plugin delete",
+    "connection delete",
+    "user delete",
+    "group delete",
 ]);
 export function isAllowedCleanupAction(resource, action) {
     return ALLOWED_CLEANUP_ACTIONS.has(`${resource} ${action}`);
@@ -391,7 +398,7 @@ function structuredExamples(examples, examplePayload) {
  * (`dss commands run`, `dss agent contract`) never loads the TypeBox graph.
  * The content matches `typeBoxCommandOutputSchemas()` exactly; parity and
  * freshness are enforced by tests/cli/discovery-output-schemas.test.ts and
- * `bun run check`.
+ * `bun run verify`.
  */
 const actionOutputSchemas = actionOutputSchemasMetadata
     .schemas;
@@ -764,6 +771,20 @@ const STRING_OUTPUT_ACTIONS = new Set([
     "log",
     "log-url",
 ]);
+/**
+ * `resource.action` shapes that differ from the bare-action-name sets above:
+ * `contents`/`usages`/`project-timeline` are array-named elsewhere, and
+ * `download`/`diff` are string-named elsewhere, but these handlers return the
+ * opposite shape. Pinned by tests/cli/output-shapes.test.ts.
+ */
+const SCOPED_OUTPUT_SHAPES = {
+    "folder.contents": "array",
+    "plugin.usages": "object",
+    "plugin.download": "object",
+    "dataset.download": "object",
+    "project-library.get": "string",
+    "project-library.diff": "object",
+};
 function inferOutputShape(resource, action) {
     if (resource === "project-git") {
         if (action === "branches" || action === "tags" || action === "list-libraries")
@@ -777,14 +798,15 @@ function inferOutputShape(resource, action) {
         || resource === "version") {
         return "object";
     }
+    // Resource-scoped rules come first: the bare-name sets below classify by
+    // action alone and would otherwise misfile same-named actions elsewhere.
+    const scoped = SCOPED_OUTPUT_SHAPES[`${resource}.${action}`];
+    if (scoped !== undefined)
+        return scoped;
     if (/^list(-|$)/.test(action))
         return "array";
     if (ARRAY_OUTPUT_ACTIONS.has(action))
         return "array";
-    if (resource === "dataset" && action === "download")
-        return "object";
-    if (resource === "project-library" && action === "get")
-        return "string";
     if (STRING_OUTPUT_ACTIONS.has(action))
         return "string";
     return "object";

package/dist/src/cli/env.js

@@ -1,6 +1,5 @@
 import { readFileSync, } from "node:fs";
-import { dirname, resolve, } from "node:path";
-import { fileURLToPath, } from "node:url";
+import { resolve, } from "node:path";
 const projectEnvVars = new Set();
 const installEnvVars = new Set();
 /**
@@ -42,7 +41,7 @@ export function loadEnvFile() {
     // CLI. First writer wins below, so cwd must be listed first.
     const dirs = [
         process.cwd(),
-        resolve(dirname(fileURLToPath(import.meta.url)), "..", ".."),
+        resolve(import.meta.dir, "..", ".."),
     ];
     for (const [index, dir,] of dirs.entries()) {
         try {

package/dist/src/cli/helpers/app-permissions.d.ts

@@ -43,7 +43,7 @@ export declare function buildAppPermissionsSnapshot(projectKey: string, dssUrl:
 export declare function writeAppPermissionsSnapshot(filePath: string, snapshot: AppPermissionsSnapshot): void;
 /** Validate envelope shape, version, and hash integrity. Never echoes permission payloads. */
 export declare function parseAppPermissionsSnapshot(text: string, source: string): AppPermissionsSnapshot;
-export declare function readAppPermissionsSnapshot(filePath: string): AppPermissionsSnapshot;
+export declare function readAppPermissionsSnapshot(filePath: string): Promise<AppPermissionsSnapshot>;
 /**
  * Refuse to use a snapshot outside the exact project *and* DSS server it was captured
  * from. Access-control rules are server-scoped: the same project key, users, and groups

package/dist/src/cli/helpers/app-permissions.js

@@ -153,10 +153,10 @@ export function parseAppPermissionsSnapshot(text, source) {
         permissions,
     };
 }
-export function readAppPermissionsSnapshot(filePath) {
+export async function readAppPermissionsSnapshot(filePath) {
     let text;
     try {
-        text = fs.readFileSync(filePath, "utf-8");
+        text = await fs.promises.readFile(filePath, "utf-8");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/src/cli/helpers/cleanup.d.ts

@@ -1,3 +1,5 @@
 import type { CleanupLedgerEntry } from "../../utils/cleanup-ledger.js";
 export declare function projectArg(projectKey: string | undefined): string[];
+/** Input field that identifies the created object, when the result does not. */
+export declare function cleanupInputIdentifierField(resource: string, action: string): string | undefined;
 export declare function cleanupLedgerEntry(resource: string, action: string, args: string[], flags: Record<string, string | boolean>, result: unknown, projectKey: string | undefined): CleanupLedgerEntry | undefined;

package/dist/src/cli/helpers/cleanup.js

@@ -35,6 +35,30 @@ function createInputFromFlags(flags) {
         return undefined;
     }
 }
+/**
+ * Creates whose DSS response carries no identifier: the cleanup ledger pins the
+ * created object from this field of the `--data`/`--data-file` input instead.
+ * `--stdin` cannot be replayed, so the CLI rejects it with `--record-cleanup`
+ * before mutating.
+ */
+const CLEANUP_INPUT_IDENTIFIER_FIELDS = {
+    "workspace.create": "workspaceKey",
+    "connection.create": "name",
+    "user.create": "login",
+    "group.create": "name",
+};
+/** Input field that identifies the created object, when the result does not. */
+export function cleanupInputIdentifierField(resource, action) {
+    return CLEANUP_INPUT_IDENTIFIER_FIELDS[`${resource}.${action}`];
+}
+function inputIdentifier(resource, action, flags) {
+    const field = cleanupInputIdentifierField(resource, action);
+    if (!field)
+        return undefined;
+    const input = resultRecord(createInputFromFlags(flags));
+    const identifier = stringField(input, [field,]);
+    return identifier ? { identifier, input, } : undefined;
+}
 export function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
     const record = resultRecord(result);
     // A notebook save is ledger-eligible only when it created the notebook:
@@ -77,6 +101,22 @@ export function cleanupLedgerEntry(resource, action, args, flags, result, projec
                 cleanup: { argv: ["dataset", "delete", name, "--if-exists", ...withProject,], },
             };
         }
+        case "dataset.create-managed": {
+            // The handler returns `created` as the dataset name and the project
+            // DSS created it in, which wins over the requested project key.
+            const name = stringField(record, ["created", "name",]) ?? flags["name"];
+            if (!name)
+                return undefined;
+            const landedProject = stringField(record, ["projectKey",]) ?? project;
+            return {
+                ...base,
+                ...(landedProject ? { projectKey: landedProject, } : {}),
+                name,
+                cleanup: {
+                    argv: ["dataset", "delete", name, "--if-exists", ...projectArg(landedProject),],
+                },
+            };
+        }
         case "recipe.create": {
             const name = stringField(record, ["created", "recipeName", "name",])
                 ?? flags["name"];
@@ -199,6 +239,78 @@ export function cleanupLedgerEntry(resource, action, args, flags, result, projec
                 cleanup: { argv: ["ml-task", "delete", analysisId, taskId, ...withProject,], },
             };
         }
+        case "ml-task.create-for-dataset": {
+            // This create opens a new visual analysis around the task, so cleanup
+            // removes the whole analysis rather than leaving an empty one behind.
+            const analysisId = stringField(record, ["analysisId",]);
+            if (!analysisId)
+                return undefined;
+            return {
+                ...base,
+                id: analysisId,
+                cleanup: { argv: ["analysis", "delete", analysisId, "--if-exists", ...withProject,], },
+            };
+        }
+        case "saved-model.create-external": {
+            const id = stringField(record, ["id",]);
+            if (!id)
+                return undefined;
+            const landedProject = stringField(record, ["projectKey",]) ?? project;
+            return {
+                ...base,
+                ...(landedProject ? { projectKey: landedProject, } : {}),
+                id,
+                name: args[0],
+                cleanup: {
+                    argv: ["saved-model", "delete", id, "--if-exists", ...projectArg(landedProject),],
+                },
+            };
+        }
+        case "project-folder.create-child": {
+            // `created` falls back to the requested name when DSS omits the id,
+            // and a name cannot address a folder delete: only `id` pins it.
+            const id = stringField(record, ["id",]);
+            if (!id)
+                return undefined;
+            return {
+                ...base,
+                id,
+                name: flags["name"],
+                cleanup: { argv: ["project-folder", "delete", id, "--if-exists",], },
+            };
+        }
+        case "data-collection.create": {
+            const id = stringField(record, ["id",]);
+            if (!id)
+                return undefined;
+            return {
+                ...base,
+                id,
+                cleanup: { argv: ["data-collection", "delete", id,], },
+            };
+        }
+        case "plugin.create-dev": {
+            const id = stringField(record, ["created",]) ?? args[0];
+            if (!id)
+                return undefined;
+            return {
+                ...base,
+                id,
+                cleanup: { argv: ["plugin", "delete", id,], },
+            };
+        }
+        case "connection.create":
+        case "user.create":
+        case "group.create": {
+            const pinned = inputIdentifier(resource, action, flags);
+            if (!pinned)
+                return undefined;
+            return {
+                ...base,
+                name: pinned.identifier,
+                cleanup: { argv: [resource, "delete", pinned.identifier, "--if-exists",], },
+            };
+        }
         case "data-quality.create-rule": {
             const ruleId = stringField(record, ["id", "created",]);
             if (!ruleId)
@@ -222,8 +334,11 @@ export function cleanupLedgerEntry(resource, action, args, flags, result, projec
                 cleanup: { argv: ["code-env", "delete", lang, name, "--if-exists",], },
             };
         }
-        case "streaming-endpoint.create": {
-            const id = args[0];
+        case "streaming-endpoint.create":
+        case "streaming-endpoint.create-managed": {
+            const id = stringField(record, ["created",]) ?? args[0];
+            if (!id)
+                return undefined;
             return {
                 ...base,
                 id,
@@ -240,15 +355,14 @@ export function cleanupLedgerEntry(resource, action, args, flags, result, projec
             };
         }
         case "workspace.create": {
-            const input = resultRecord(createInputFromFlags(flags));
-            const workspaceKey = stringField(input, ["workspaceKey",]);
-            if (!workspaceKey)
+            const pinned = inputIdentifier(resource, action, flags);
+            if (!pinned)
                 return undefined;
             return {
                 ...base,
-                id: workspaceKey,
-                name: stringField(input, ["displayName",]),
-                cleanup: { argv: ["workspace", "delete", workspaceKey,], },
+                id: pinned.identifier,
+                name: stringField(pinned.input, ["displayName",]),
+                cleanup: { argv: ["workspace", "delete", pinned.identifier,], },
             };
         }
         case "project-library.create-file":

package/dist/src/cli/helpers/flow-zone.d.ts

@@ -56,7 +56,7 @@ export declare function dedupeFlowZonePlanItems(items: FlowZoneItemInput[]): Flo
 export declare function flowZonePlanItemKeys(plan: FlowZoneOrganizePlan): Set<string>;
 export declare function validateUniqueFlowZoneAssignments(plan: FlowZoneOrganizePlan): void;
 export declare function parseFlowZoneOrganizePlan(input: Record<string, unknown>): FlowZoneOrganizePlan;
-export declare function readFlowZoneOrganizePlan(flags: Record<string, string | boolean>, usage: string): FlowZoneOrganizePlan;
+export declare function readFlowZoneOrganizePlan(flags: Record<string, string | boolean>, usage: string): Promise<FlowZoneOrganizePlan>;
 export declare function findFlowZoneForPlan(zones: FlowZone[], plan: FlowZoneOrganizeZonePlan): FlowZone | undefined;
 export declare function ensureFlowZonePlanTarget(plan: FlowZoneOrganizeZonePlan, existing: FlowZone | undefined): void;
 export declare function flowZoneExplicitItems(zone: FlowZone): FlowZoneItemInput[];

package/dist/src/cli/helpers/flow-zone.js

@@ -1,8 +1,7 @@
-import { readFileSync, } from "node:fs";
 import { ClientValidationError, } from "../../errors.js";
 import { asRecord, } from "../../utils/records.js";
 import { compareStrings, } from "../../utils/stable-hash.js";
-import { finiteNumberField, jsonInput, optionalStringField, parseJsonObject, requiredStringArray, splitCsvFlag, } from "../coerce.js";
+import { finiteNumberField, jsonInput, optionalStringField, parseJsonObject, readTextFile, requiredStringArray, splitCsvFlag, } from "../coerce.js";
 import { commandUsage, } from "../syntax.js";
 import { UsageError, } from "../usage.js";
 export function flowZoneId(value) {
@@ -257,9 +256,9 @@ export function parseFlowZoneOrganizePlan(input) {
     validateUniqueFlowZoneAssignments(plan);
     return plan;
 }
-export function readFlowZoneOrganizePlan(flags, usage) {
+export async function readFlowZoneOrganizePlan(flags, usage) {
     const data = typeof flags["file"] === "string"
-        ? parseJsonObject(readFileSync(flags["file"], "utf-8"), flags["file"])
+        ? parseJsonObject(await readTextFile(flags["file"]), flags["file"])
         : jsonInput(flags);
     if (!data) {
         throw new UsageError(`--data, --data-file, --file, or --stdin is required. Usage: ${usage}`, "missing_required_flag");

package/dist/src/cli/list-output.d.ts

@@ -1,3 +1,7 @@
+import { type CompactListField } from "./list-shapes.js";
+type Item = Record<string, unknown>;
+/** One compact field of a DSS list item, as `RESOURCE.list` prints it. */
+export declare function compactValue(item: Item, spec: CompactListField): unknown;
 /**
  * Shape a `*.list` result for agents: `--contains` filters on identifier
  * fields, `--limit` caps the count (a `list_truncated` warning reports the
@@ -5,3 +9,4 @@
  * `--full` or `--fields` asks for the DSS objects.
  */
 export declare function shapeListResult(resource: string, result: unknown, flags: Record<string, string | boolean>): unknown;
+export {};

package/dist/src/cli/list-output.js

@@ -4,10 +4,19 @@ import { enqueueCliWarning, } from "./output.js";
 function record(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
-function compactValue(item, spec) {
+function valueAt(item, path) {
     let value = item;
-    for (const key of spec.path.split("."))
+    for (const key of path.split("."))
         value = record(value)[key];
+    return value;
+}
+/** One compact field of a DSS list item, as `RESOURCE.list` prints it. */
+export function compactValue(item, spec) {
+    const value = valueAt(item, spec.path);
+    if (value === undefined && spec.fallback
+        && valueAt(item, spec.fallback.when) === spec.fallback.equals) {
+        return spec.fallback.value;
+    }
     if (spec.roleRefs !== true)
         return value;
     // Dataset refs across every role of recipe inputs/outputs (`{main:{items:[{ref}]}}`).

package/dist/src/cli/list-shapes.d.ts

@@ -9,6 +9,12 @@ export interface CompactListField {
     path: string;
     /** Flatten recipe roles (`{main:{items:[{ref}]}}`) to the dataset refs. */
     roleRefs?: true;
+    /** Value when `path` is absent and the item's `when` path equals `equals`. */
+    fallback?: {
+        when: string;
+        equals: unknown;
+        value: unknown;
+    };
     schema: Record<string, unknown>;
 }
 /**

package/dist/src/cli/list-shapes.js

@@ -51,7 +51,12 @@ export const COMPACT_LIST_FIELDS = {
         id: field("def.id", STRING),
         name: field("def.name", STRING),
         type: field("def.type", STRING),
-        state: field("state", STRING),
+        // DSS lists in-progress jobs with `stableState: false` and no `state`
+        // (COMPUTING_DEPS or RUNNING); `job get` reports the exact phase.
+        state: {
+            ...field("state", STRING),
+            fallback: { when: "stableState", equals: false, value: "RUNNING", },
+        },
         startTime: field("startTime", NUMBER),
         endTime: field("endTime", NUMBER),
     },
@@ -83,6 +88,7 @@ export const COMPACT_LIST_FIELDS = {
         id: field("id", STRING),
         version: field("version", STRING),
         label: field("meta.label", STRING),
+        isDev: field("isDev", BOOLEAN),
     },
     macro: {
         runnableType: field("runnableType", STRING),

package/dist/src/cli/output-schemas.d.ts

@@ -3,7 +3,7 @@
  * the single source of truth for `src/generated/action-output-schemas.json`,
  * which discovery reads as plain data so no TypeBox schema graph loads on the
  * discovery path. Regenerate with
- * `bun scripts/generate-action-output-schemas.mjs`; `bun run check` fails when
+ * `bun scripts/generate-action-output-schemas.mjs`; `bun run verify` fails when
  * the generated file is stale. SDK validation keeps using the TypeBox schema
  * objects from `packages/types` directly and never depends on the generated file.
  */

package/dist/src/cli/output-schemas.js

@@ -72,7 +72,7 @@ let commandOutputSchemas;
  * the single source of truth for `src/generated/action-output-schemas.json`,
  * which discovery reads as plain data so no TypeBox schema graph loads on the
  * discovery path. Regenerate with
- * `bun scripts/generate-action-output-schemas.mjs`; `bun run check` fails when
+ * `bun scripts/generate-action-output-schemas.mjs`; `bun run verify` fails when
  * the generated file is stale. SDK validation keeps using the TypeBox schema
  * objects from `packages/types` directly and never depends on the generated file.
  */

package/dist/src/cli/output.js

@@ -193,6 +193,13 @@ export function commandFailureMessage(result) {
             if (typeof message === "string" && message.length > 0)
                 return message;
         }
+        if (record.timedOut === true && typeof record.jobId === "string"
+            && typeof record.progress === "object" && typeof record.state === "string") {
+            // A job wait result: the timeout only stopped polling, the DSS job is
+            // still running (and was not cancelled).
+            const resume = typeof record.resume === "string" ? ` Resume with: ${record.resume}` : "";
+            return `Timed out waiting for job ${record.jobId} after ${record.elapsedMs}ms (last known state: ${record.state}); the job is still running in DSS and was not cancelled.${resume}`;
+        }
         const state = typeof record.state === "string"
             ? record.state
             : typeof record.outcome === "string"

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

@@ -49,7 +49,7 @@ export declare function buildVersionPayload(input: {
 export declare const PACKAGE_ROOT: string | undefined;
 export declare const CLI_VERSION: string;
 export declare const CLI_GIT_REVISION: string | undefined;
-export declare const AGENT_CONTRACT_VERSION = 4;
+export declare const AGENT_CONTRACT_VERSION = 5;
 export declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
-export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v4.json";
+export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v5.json";
 export declare function cliVersionResult(): CliVersionPayload;

package/dist/src/cli/version.js

@@ -1,8 +1,7 @@
 import { readdirSync, readFileSync, statSync, } from "node:fs";
 import { dirname, resolve, } from "node:path";
-import { fileURLToPath, } from "node:url";
 export function findPackageRoot() {
-    let dir = dirname(fileURLToPath(import.meta.url));
+    let dir = import.meta.dir;
     for (let i = 0; i < 5; i++) {
         try {
             readFileSync(resolve(dir, "package.json"), "utf-8");
@@ -133,7 +132,7 @@ export function gitRevision(packageRoot) {
     const full = gitFullRevision(packageRoot);
     return full ? full.slice(0, 7) : undefined;
 }
-export function detectLoadSource(modulePath = fileURLToPath(import.meta.url)) {
+export function detectLoadSource(modulePath = import.meta.path) {
     return modulePath.replaceAll("\\", "/").includes("/dist/") ? "dist" : "source";
 }
 export function buildMetadataRevision(packageRoot) {
@@ -204,9 +203,9 @@ export function buildVersionPayload(input) {
 export const PACKAGE_ROOT = findPackageRoot();
 export const CLI_VERSION = packageVersion(PACKAGE_ROOT);
 export const CLI_GIT_REVISION = gitRevision(PACKAGE_ROOT);
-export const AGENT_CONTRACT_VERSION = 4;
+export const AGENT_CONTRACT_VERSION = 5;
 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-v4.json";
+export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v5.json";
 export function cliVersionResult() {
     // Only code actually loaded from dist/ may report dist provenance; an
     // inherited DSS_LOAD_SOURCE on a source run is ignored.

package/dist/src/cli.js

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
-import * as fs from "node:fs/promises";
 import { homedir, } from "node:os";
 import { resolve, } from "node:path";
-import { num, seenJsonInputCredentials, unknownJsonInput, } from "./cli/coerce.js";
+import { num, resultRecord, seenJsonInputCredentials, stringField, unknownJsonInput, } from "./cli/coerce.js";
 import { commands, } from "./cli/commands/index.js";
 import { ambientProjectKey, loadEnvFile, } from "./cli/env.js";
 import { executionMode, FLAG_ALIASES, isFlagValueToken, parseArgs, rawPositionals, } from "./cli/flags.js";
-import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
+import { cleanupInputIdentifierField, cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
 import { commandFailureExitCode, CommandResultFailure, enqueueCliWarning, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
 import { shapeCommandResult, } from "./cli/result-shapes.js";
 import { currentCommandContext, resolveCredentials, resolveLoginCredentials, } from "./cli/runtime.js";
@@ -786,7 +785,7 @@ async function commandsRunResult(flags) {
         : projectResultFields(registry, selectors, () => Object.keys(contract.commandActionSummary()).sort());
     if (typeof outputPath === "string") {
         const exported = selectedRegistry;
-        await fs.writeFile(outputPath, `${JSON.stringify(exported)}\n`, "utf-8");
+        await Bun.write(outputPath, `${JSON.stringify(exported)}\n`);
         return { path: outputPath, };
     }
     return selectedRegistry;
@@ -802,8 +801,9 @@ function assertCleanupLedgerSupported(resource, action, flags) {
     if (!contract.supportsCleanupLedger(resource, action)) {
         throw new UsageError(`--record-cleanup is not supported for ${resource} ${action}.`);
     }
-    if (resource === "workspace" && action === "create" && flags["stdin"] === true) {
-        throw new UsageError("workspace create cannot combine --record-cleanup with --stdin because the cleanup identifier cannot be replayed from a consumed stream.", "conflicting_input_sources", "Use --data or --data-file so the workspaceKey remains available for the cleanup ledger.");
+    const pinnedField = cleanupInputIdentifierField(resource, action);
+    if (pinnedField !== undefined && flags["stdin"] === true) {
+        throw new UsageError(`${resource} ${action} cannot combine --record-cleanup with --stdin because the cleanup identifier cannot be replayed from a consumed stream.`, "conflicting_input_sources", `Use --data or --data-file so the ${pinnedField} remains available for the cleanup ledger.`);
     }
 }
 /**
@@ -856,11 +856,36 @@ async function preflightCleanupLedgerForFlags(client, flags) {
     }
 }
 /**
- * Append the cleanup entry for a completed handler result. Callers must pass the
- * raw, unprojected result and must call this before any failure exit code is
- * raised: an indeterminate post-POST outcome stays addressable only when the
- * ledger records it first. Eligibility (dry runs, skipped work, an explicit
- * `cleanupEligible:false`) is decided by `cleanupLedgerEntry`, never here.
+ * What the command result already says about the created object, so a failed
+ * ledger write never hides it: the `created`/`saved` receipt, the object `id`
+ * and `name`, and the project key DSS landed it in. Fields stay distinct (a
+ * name is not an id) and absent ones are omitted rather than guessed.
+ */
+function createdObjectFromResult(result, fallbackProjectKey) {
+    const record = resultRecord(result);
+    const created = stringField(record, ["created", "saved", "usedProjectKey",]);
+    const id = stringField(record, ["id",]);
+    const name = stringField(record, ["name",]);
+    const projectKey = stringField(record, ["projectKey", "usedProjectKey", "targetProjectKey",])
+        ?? fallbackProjectKey;
+    return {
+        ...(created ? { created, } : {}),
+        ...(id ? { id, } : {}),
+        ...(name ? { name, } : {}),
+        ...(projectKey ? { projectKey, } : {}),
+    };
+}
+/**
+ * Append the cleanup entry for a completed handler result. Callers must call
+ * this before any failure exit code is raised: an indeterminate post-POST
+ * outcome stays addressable only when the ledger records it first. Eligibility
+ * (dry runs, skipped work, an explicit `cleanupEligible:false`) is decided by
+ * `cleanupLedgerEntry`, never here.
+ *
+ * The mutation has already happened when this runs, so every failure here is
+ * an `ambiguous_outcome` that says so (`mutationSucceeded: true`,
+ * `cleanupRecorded: false`) and carries the created identifier/project key:
+ * callers must never retry the create, only clean up or record it themselves.
  */
 async function recordCleanupLedgerEntry(client, resource, action, args, flags, result, projectKey) {
     const ledgerPath = flags["record-cleanup"];
@@ -868,15 +893,33 @@ async function recordCleanupLedgerEntry(client, resource, action, args, flags, r
         return;
     const entry = cleanupLedgerEntry(resource, action, args, flags, result, projectKey);
     if (entry) {
-        await appendCleanupLedgerEntry(ledgerPath, entry, client.getBaseUrl());
+        try {
+            await appendCleanupLedgerEntry(ledgerPath, entry, client.getBaseUrl());
+        }
+        catch (error) {
+            throw new ClientValidationError(`Mutation completed but the cleanup entry for ${resource} ${action} could not be recorded: ${error instanceof Error ? error.message : String(error)}`, "ambiguous_outcome", "The mutation already succeeded: do not retry it. Remove the created object manually or append this cleanup entry to the ledger yourself.", {
+                resource,
+                action,
+                ledgerPath,
+                mutationSucceeded: true,
+                cleanupRecorded: false,
+                ...createdObjectFromResult(result, projectKey),
+                cleanup: entry.cleanup,
+            });
+        }
         return;
     }
-    const record = result !== null && typeof result === "object" && !Array.isArray(result)
-        ? result
-        : {};
+    const record = resultRecord(result);
     if (record.skipped !== undefined || record.cleanupEligible === false)
         return;
-    throw new ClientValidationError(`Mutation completed but no cleanup entry could be derived for ${resource} ${action}.`, "ambiguous_outcome", "Inspect the created object and remove it manually; do not assume the requested cleanup ledger contains it.", { resource, action, ledgerPath, });
+    throw new ClientValidationError(`Mutation completed but no cleanup entry could be derived for ${resource} ${action}.`, "ambiguous_outcome", "The mutation already succeeded: do not retry it. Inspect the created object and remove it manually; the requested cleanup ledger does not contain it.", {
+        resource,
+        action,
+        ledgerPath,
+        mutationSucceeded: true,
+        cleanupRecorded: false,
+        ...createdObjectFromResult(result, projectKey),
+    });
 }
 async function runBatch(flags) {
     const payload = unknownJsonInput(flags);
@@ -1306,15 +1349,21 @@ function buildErrorReport(err, contextOverride) {
     if (err instanceof ClientValidationError
         && (err.code === "ambiguous_outcome" || err.code === "assertion_failed"
             || err.code === "long_running_failure")) {
+        // The DSS response behind an indeterminate outcome stays visible (status,
+        // sanitized message), e.g. a 500 that names the conflicting project key.
+        const cause = err.cause instanceof DataikuError ? err.cause : undefined;
+        const diagnostics = cause ? dssDiagnosticDetails(cause) : {};
+        const details = { ...diagnostics, ...err.details, };
         return {
             type: "error",
             error: err.message,
             code: err.code,
             category: "dss",
             exitCode,
+            ...(cause ? { status: cause.status, } : {}),
             retryable: false,
             ...(err.hint ? { hint: err.hint, } : {}),
-            ...(err.details ? { details: err.details, } : {}),
+            ...(Object.keys(details).length > 0 ? { details, } : {}),
             ...scope,
         };
     }

package/dist/src/client.d.ts

@@ -153,7 +153,13 @@ export declare class DataikuClient {
     private readonly maxResponseBodyBytes;
     private readonly retryMaxAttempts;
     private readonly verbose;
-    private readonly tlsOptions;
+    /**
+     * Connection pool carrying this client's TLS settings (custom CA, disabled
+     * verification). A session never shares connections with plain `fetch` or
+     * another client, so a connection opened with relaxed TLS cannot serve a
+     * client that expects strict verification. Default-TLS clients use plain fetch.
+     */
+    private readonly session;
     private readonly onTrace;
     private readonly onValidationWarning;
     private projectsResource?;
@@ -294,7 +300,8 @@ export declare class DataikuClient {
      * When the response exceeds the cap, earlier bytes are discarded, only
      * the tail is kept and `truncated` is true — so callers that need the end
      * of a large document (e.g. job logs) stay bounded without losing the most
-     * recent content. The read runs under the request deadline.
+     * recent content. The request timeout applies per received chunk (a stall
+     * deadline), not to the whole transfer.
      */
     getTextTailLimited(path: string, maxBytes: number): Promise<{
         text: string;
@@ -385,6 +392,11 @@ export declare class DataikuClient {
      * Returns `truncated: true` when bytes had to be dropped. Bytes that fall
      * in the middle of a UTF-8 character are dropped from both ends so the
      * decoded text never contains a replacement character.
+     *
+     * The request timeout applies per chunk (a stall deadline), like the
+     * streaming path: a large body that keeps arriving is read to EOF however
+     * long the whole transfer takes, while a body that stops sending for longer
+     * than the timeout fails with the body-read timeout error.
      */
     private readBodyTextTail;
     private buildResponseTooLargeError;