dataiku-sdk 4.0.0 → 4.2.0

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

@@ -1,7 +1,8 @@
 /**
- * Compact default results of the four large read commands (`job get`,
- * `dataset info`, `dataset get`, `project get`), plus the single dispatch
- * point for compacting command results (`shapeCommandResult`).
+ * Compact default results of the large read commands (`job get`,
+ * `dataset info`, `dataset get`, `project get`, `scenario get-run`,
+ * `scenario last-runs`), plus the single dispatch point for compacting
+ * command results (`shapeCommandResult`).
  *
  * The SDK resources keep returning the raw DSS objects; only the CLI compacts.
  * `--full` returns the DSS object unchanged, and `--fields` projects DSS paths
@@ -213,16 +214,239 @@ function shapeProjectGet(result) {
     const pruned = record(pruneEmpty(settings));
     return { ...pruned, deniedPermissions, };
 }
+/** Scenario/step/job outcomes that count as a failure worth diagnosing. */
+const FAILED_OUTCOMES = { FAILED: true, ABORTED: true, };
+function isFailedOutcome(value) {
+    return typeof value === "string" && FAILED_OUTCOMES[value] === true;
+}
+/** Message of a DSS `thrown` exception object (`{ clazz, message, ... }`). */
+function thrownMessage(value) {
+    const thrown = record(value);
+    return nonEmptyString(thrown["message"]) ?? nonEmptyString(thrown["detailedMessage"]);
+}
+function reportItems(stepRun, type) {
+    const items = stepRun["additionalReportItems"];
+    return Array.isArray(items)
+        ? items.filter((item) => isRecord(item) && item["type"] === type)
+        : [];
+}
+/**
+ * One `stepRuns[]` entry: the step identity and outcome, the datasets it built
+ * (`BUILT_DATASET` report items) and the jobs it ran (`JOB_EXECUTED`, with the
+ * thrown message). The job log tail DSS embeds in the report is dropped.
+ */
+function shapeScenarioStep(stepRun, runProjectKey) {
+    const fields = record(stepRun);
+    const step = record(fields["step"]);
+    const result = record(fields["result"]);
+    const datasets = reportItems(fields, "BUILT_DATASET").map((item) => {
+        const target = record(item["target"]);
+        const partition = target["partition"];
+        return defined({
+            dataset: target["datasetName"],
+            projectKey: typeof target["projectKey"] === "string" && target["projectKey"] !== runProjectKey
+                ? target["projectKey"]
+                : undefined,
+            partition: typeof partition === "string" && partition !== "NP" ? partition : undefined,
+            outcome: item["outcome"],
+        });
+    });
+    const jobs = reportItems(fields, "JOB_EXECUTED").map((item) => defined({
+        jobId: item["jobId"],
+        outcome: item["outcome"],
+        message: thrownMessage(item["thrown"]),
+    }));
+    return defined({
+        id: step["id"],
+        name: step["name"],
+        type: step["type"],
+        outcome: result["outcome"],
+        message: thrownMessage(result["thrown"]),
+        datasets: datasets.length > 0 ? datasets : undefined,
+        jobs: jobs.length > 0 ? jobs : undefined,
+    });
+}
+/**
+ * First failure of a shaped run: the failed step, its failed job and dataset,
+ * and the most specific message (job, then step, then scenario).
+ */
+function firstScenarioFailure(steps, runThrown) {
+    for (const step of steps) {
+        const jobs = step["jobs"] ?? [];
+        const job = jobs.find((entry) => isFailedOutcome(entry["outcome"]));
+        if (!isFailedOutcome(step["outcome"]) && !job)
+            continue;
+        const datasets = step["datasets"] ?? [];
+        const dataset = datasets.find((entry) => isFailedOutcome(entry["outcome"]));
+        return defined({
+            stepId: step["id"],
+            jobId: job?.["jobId"],
+            dataset: dataset?.["dataset"],
+            message: nonEmptyString(job?.["message"]) ?? nonEmptyString(step["message"])
+                ?? thrownMessage(runThrown),
+        });
+    }
+    const message = thrownMessage(runThrown);
+    return message === undefined ? undefined : { message, };
+}
+function projectKeyArgs(projectKey) {
+    return typeof projectKey === "string" && projectKey.length > 0
+        ? ["--project-key", projectKey,]
+        : [];
+}
+/**
+ * Next-step argv for a failure. With the failed recipe known: its code and the
+ * schemas of its inputs (what a "column not found" or type error needs), then
+ * the job's error log; else the job's error log, else the scenario run log.
+ */
+function failureNextSteps(failure, scenarioId, runId, projectKey, activity) {
+    const pk = projectKeyArgs(projectKey);
+    const inspect = activity
+        ? [
+            ["dss", "recipe", "cat", activity.recipe, ...pk,],
+            ...activity.inputs.slice(0, 3).map((input) => ["dss", "dataset", "schema", input, ...pk,]),
+        ]
+        : [];
+    if (typeof failure["jobId"] === "string") {
+        return [...inspect, ["dss", "job", "log", failure["jobId"], "--errors-only", ...pk,],];
+    }
+    if (typeof scenarioId !== "string" || typeof runId !== "string")
+        return undefined;
+    const stepArgs = typeof failure["stepId"] === "string" ? ["--step-id", failure["stepId"],] : [];
+    return [["dss", "scenario", "log", scenarioId, runId, ...stepArgs, ...pk,],];
+}
+/** Scenario identity of a run object (`scenarioRun` or a last-runs item). */
+function runScenarioIdentity(run) {
+    const scenario = record(run["scenario"]);
+    const target = record(record(run["result"])["target"]);
+    return {
+        scenarioId: scenario["id"] ?? target["scenarioId"],
+        projectKey: scenario["projectKey"] ?? target["projectKey"],
+    };
+}
+function runTrigger(run) {
+    const trigger = record(record(run["trigger"])["trigger"]);
+    const shaped = defined({
+        type: nonEmptyString(trigger["type"]),
+        name: nonEmptyString(trigger["name"]),
+    });
+    return Object.keys(shaped).length > 0 ? shaped : undefined;
+}
+/**
+ * Failure diagnosis of a raw `scenario get-run` report: the first failure
+ * (`{ stepId, jobId, dataset, message }`) and the next command(s) to run as
+ * argv arrays. With the failed recipe known, `hint` names the edit-and-rerun
+ * loop, so the agent does not look up the write commands. Empty when the run did not fail.
+ */
+export function scenarioRunDiagnosis(details, activity) {
+    const fields = record(details);
+    const run = record(fields["scenarioRun"]);
+    const result = record(run["result"]);
+    const { scenarioId, projectKey, } = runScenarioIdentity(run);
+    const steps = Array.isArray(fields["stepRuns"])
+        ? fields["stepRuns"].map((stepRun) => shapeScenarioStep(stepRun, projectKey))
+        : [];
+    const failed = isFailedOutcome(result["outcome"])
+        || steps.some((step) => isFailedOutcome(step["outcome"]));
+    const failure = failed ? firstScenarioFailure(steps, result["thrown"]) : undefined;
+    if (!failure)
+        return {};
+    if (!activity) {
+        const next = failureNextSteps(failure, scenarioId, run["runId"], projectKey, undefined);
+        return next ? { failure, next, } : { failure, };
+    }
+    const located = { ...failure, recipe: activity.recipe, inputs: activity.inputs, };
+    const next = failureNextSteps(located, scenarioId, run["runId"], projectKey, activity);
+    const pk = projectKeyArgs(projectKey).join(" ");
+    const suffix = pk === "" ? "" : ` ${pk}`;
+    const rerun = typeof scenarioId === "string"
+        ? `; rerun: dss scenario run-and-wait ${scenarioId}${suffix}`
+        : "";
+    const hint = `To fix: dss recipe get-payload ${activity.recipe} --output FILE${suffix}, edit FILE, `
+        + `dss recipe set-payload ${activity.recipe} --file FILE${suffix}${rerun}.`;
+    return next ? { failure: located, next, hint, } : { failure: located, hint, };
+}
+/**
+ * `scenario get-run`: run identity, outcome, timing, trigger, per-step
+ * datasets/jobs, the first failure, and next-step argv. Never the trigger
+ * auth context, run-as user, API key metadata, or job log tails.
+ */
+function shapeScenarioGetRun(result) {
+    if (!isRecord(result) || !isRecord(result["scenarioRun"]))
+        return result;
+    const run = result["scenarioRun"];
+    const runResult = record(run["result"]);
+    const { scenarioId, projectKey, } = runScenarioIdentity(run);
+    const start = typeof run["start"] === "number" ? run["start"] : undefined;
+    const end = typeof run["end"] === "number" ? run["end"] : undefined;
+    const steps = Array.isArray(result["stepRuns"])
+        ? result["stepRuns"].map((stepRun) => shapeScenarioStep(stepRun, projectKey))
+        : [];
+    const { failure, next, } = scenarioRunDiagnosis(result);
+    return defined({
+        runId: run["runId"],
+        scenarioId,
+        projectKey,
+        outcome: runResult["outcome"],
+        start,
+        end,
+        durationMs: start !== undefined && end !== undefined && end >= start ? end - start : undefined,
+        trigger: runTrigger(run),
+        steps,
+        failure,
+        next,
+    });
+}
+/**
+ * One `scenario last-runs` item: identity, outcome, timing, trigger, failure
+ * message, and for a failed run the `scenario get-run` argv that shows why.
+ */
+function shapeScenarioRunSummary(item) {
+    if (!isRecord(item))
+        return item;
+    const result = record(item["result"]);
+    const message = thrownMessage(result["thrown"]);
+    const { scenarioId, projectKey, } = runScenarioIdentity(item);
+    const next = isFailedOutcome(result["outcome"]) && typeof scenarioId === "string"
+        && typeof item["runId"] === "string"
+        ? [[
+                "dss",
+                "scenario",
+                "get-run",
+                scenarioId,
+                item["runId"],
+                ...(typeof projectKey === "string" ? ["--project-key", projectKey,] : []),
+            ],]
+        : undefined;
+    // DSS lists an in-progress run with `end: 0` and no result outcome.
+    const running = result["outcome"] === undefined && item["end"] === 0;
+    return defined({
+        runId: item["runId"],
+        outcome: running ? "RUNNING" : result["outcome"],
+        start: item["start"] ?? result["start"],
+        end: item["end"] ?? result["end"],
+        trigger: runTrigger(item),
+        failure: message === undefined ? undefined : { message, },
+        next,
+    });
+}
+/** `scenario last-runs`: one small object per run, newest first as DSS returns them. */
+function shapeScenarioLastRuns(result) {
+    return Array.isArray(result) ? result.map(shapeScenarioRunSummary) : result;
+}
 /** Compact read shapers by `resource.action`. */
 const READ_SHAPERS = {
     "job.get": shapeJobGet,
     "dataset.info": shapeDatasetInfo,
     "dataset.get": shapeDatasetGet,
     "project.get": shapeProjectGet,
+    "scenario.get-run": shapeScenarioGetRun,
+    "scenario.last-runs": shapeScenarioLastRuns,
+    "scenario.runs-by-date": shapeScenarioLastRuns,
 };
 /**
  * Compact a command result for agents: `*.list` items (filter, cap, compact
- * fields) and the four large read commands. `--full` and `--fields` bypass
+ * fields) and the large read commands. `--full` and `--fields` bypass
  * the read shapers so the DSS object (or a projection of it) is returned.
  */
 export function shapeCommandResult(resource, action, result, flags) {

package/dist/src/cli/selector-suggestions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Did-you-mean suggestions for `commands run --fields RESOURCE[.ACTION[.FIELD...]]`
+ * selectors that name no resource or action. Pure data in, strings out.
+ */
+/**
+ * Selectors worth trying instead of an unknown `resource` / `resource.action`
+ * selector, keeping any trailing `.field` path. For a known resource: the same
+ * action name under other resources (`flow.map.usage` -> `project.map.usage`),
+ * then close action names of that resource. For an unknown resource: close
+ * resource names (keeping the action), else the action under other resources.
+ *
+ * @param actionsByResource resource -> action names (`commandActionSummary()`).
+ */
+export declare function suggestSelectors(selector: string, actionsByResource: Record<string, string[]>): string[];

package/dist/src/cli/selector-suggestions.js

@@ -0,0 +1,56 @@
+/**
+ * Did-you-mean suggestions for `commands run --fields RESOURCE[.ACTION[.FIELD...]]`
+ * selectors that name no resource or action. Pure data in, strings out.
+ */
+const MAX_SUGGESTIONS = 4;
+/** Levenshtein distance with a single rolling row. */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1, }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i,];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current.push(Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** Names close to `name`: a typo (distance <= 2, <= 1 for short names) or one containing it. */
+function closeNames(name, candidates) {
+    const maxDistance = name.length >= 5 ? 2 : 1;
+    return candidates.filter((candidate) => candidate !== name
+        && (editDistance(name, candidate) <= maxDistance
+            || (name.length >= 3 && candidate.includes(name))));
+}
+/**
+ * Selectors worth trying instead of an unknown `resource` / `resource.action`
+ * selector, keeping any trailing `.field` path. For a known resource: the same
+ * action name under other resources (`flow.map.usage` -> `project.map.usage`),
+ * then close action names of that resource. For an unknown resource: close
+ * resource names (keeping the action), else the action under other resources.
+ *
+ * @param actionsByResource resource -> action names (`commandActionSummary()`).
+ */
+export function suggestSelectors(selector, actionsByResource) {
+    const [resource = "", action, ...rest] = selector.split(".");
+    const suffix = rest.length > 0 ? `.${rest.join(".")}` : "";
+    const resources = Object.keys(actionsByResource);
+    const sameActionElsewhere = action === undefined
+        ? []
+        : resources.filter((other) => other !== resource && actionsByResource[other].includes(action))
+            .map((other) => `${other}.${action}${suffix}`);
+    let suggestions;
+    if (Object.hasOwn(actionsByResource, resource)) {
+        const closeActions = action === undefined
+            ? []
+            : closeNames(action, actionsByResource[resource]).map((close) => `${resource}.${close}${suffix}`);
+        suggestions = [...sameActionElsewhere, ...closeActions,];
+    }
+    else {
+        const tail = action === undefined ? "" : `.${[action, ...rest,].join(".")}`;
+        const closeResources = closeNames(resource, resources).map((close) => `${close}${tail}`);
+        suggestions = closeResources.length > 0 ? closeResources : sameActionElsewhere;
+    }
+    return [...new Set(suggestions),].slice(0, MAX_SUGGESTIONS);
+}

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

@@ -11,7 +11,7 @@ export declare const COMMANDS_RUN_HINT = "Use `dss commands run --fields RESOURC
 export declare function unsupportedHelpFlag(): UsageError;
 export declare function noCommandError(): UsageError;
 export declare function missingActionError(resource: string, validActions: string[], usage?: string): UsageError;
-export declare function unknownResourceError(resource: string): UsageError;
+export declare function unknownResourceError(resource: string, action?: string): UsageError;
 /**
  * Agents rarely mistype; they reuse plausible flags from other commands or
  * CLIs. When the command is known, the hint is its usage line, which lists

package/dist/src/cli/usage.js

@@ -1,4 +1,29 @@
-import { commandSyntaxTree, renderNodes, syntaxHasFlag, } from "./syntax.js";
+import { suggestSelectors, } from "./selector-suggestions.js";
+import { commandSyntaxKeys, commandSyntaxTree, renderNodes, syntaxHasFlag, } from "./syntax.js";
+/**
+ * `dss resource action` commands close to a mistyped one (`flow map` -> `project map`,
+ * `recipes list` -> `recipe list`), from the syntax tree, so the error names the fix.
+ */
+function commandSuggestions(resource, action) {
+    const actionsByResource = {};
+    for (const key of commandSyntaxKeys()) {
+        const dot = key.indexOf(".");
+        (actionsByResource[key.slice(0, dot)] ??= []).push(key.slice(dot + 1));
+    }
+    // An unknown resource with no close name gets no suggestions: the same action under
+    // arbitrary resources (`pipelines list` -> `app list`) misleads more than it helps.
+    if (!Object.hasOwn(actionsByResource, resource)
+        && suggestSelectors(resource, actionsByResource).length === 0) {
+        return [];
+    }
+    return suggestSelectors(action ? `${resource}.${action}` : resource, actionsByResource)
+        .map((selector) => `dss ${selector.replace(".", " ")}`);
+}
+function suggestionHint(suggestions) {
+    return suggestions.length > 0
+        ? `Did you mean ${suggestions.map((command) => `\`${command}\``).join(" or ")}? ${COMMANDS_RUN_HINT}`
+        : COMMANDS_RUN_HINT;
+}
 export const RESOURCE_NAMES = [
     "agent",
     "app",
@@ -25,6 +50,7 @@ export const RESOURCE_NAMES = [
     "statistics",
     "discussion",
     "meaning",
+    "messaging-channel",
     "workspace",
     "metrics",
     "doctor",
@@ -122,8 +148,13 @@ export function noCommandError() {
 export function missingActionError(resource, validActions, usage) {
     return new UsageError(`Missing action for ${resource}.`, "usage_error", usage ?? COMMANDS_RUN_HINT, { resource, validActions, });
 }
-export function unknownResourceError(resource) {
-    return new UsageError(`Unknown resource: ${resource}.`, "usage_error", COMMANDS_RUN_HINT, { resource, validResources: RESOURCE_NAMES, });
+export function unknownResourceError(resource, action) {
+    const suggestions = commandSuggestions(resource, action);
+    return new UsageError(`Unknown resource: ${resource}.`, "usage_error", suggestionHint(suggestions), {
+        resource,
+        validResources: RESOURCE_NAMES,
+        ...(suggestions.length > 0 ? { suggestions, } : {}),
+    });
 }
 /**
  * Agents rarely mistype; they reuse plausible flags from other commands or
@@ -141,7 +172,8 @@ export function unknownFlagError(flagLabel, resource, action) {
     return new UsageError(message, "unknown_flag", command ? `Usage: ${renderNodes(command)}` : undefined);
 }
 export function unknownActionError(resource, action, validActions, hint) {
-    return new UsageError(`Unknown action: ${resource} ${action ?? ""}`.trim(), "usage_error", hint ?? COMMANDS_RUN_HINT, { resource, action, validActions, });
+    const suggestions = commandSuggestions(resource, action);
+    return new UsageError(`Unknown action: ${resource} ${action ?? ""}`.trim(), "usage_error", hint ?? suggestionHint(suggestions), { resource, action, validActions, ...(suggestions.length > 0 ? { suggestions, } : {}), });
 }
 export function requireArgs(args, count, usage) {
     if (args.length < count) {

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 = 5;
+export declare const AGENT_CONTRACT_VERSION = 7;
 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-v5.json";
+export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v7.json";
 export declare function cliVersionResult(): CliVersionPayload;

package/dist/src/cli/version.js

@@ -203,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 = 5;
+export const AGENT_CONTRACT_VERSION = 7;
 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-v5.json";
+export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v7.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

@@ -6,9 +6,10 @@ 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 { cleanupInputIdentifierField, cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
-import { commandFailureExitCode, CommandResultFailure, enqueueCliWarning, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
+import { commandFailureExitCode, CommandResultFailure, enqueueCliWarning, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, stdoutJson, writeCommandResult, } from "./cli/output.js";
 import { shapeCommandResult, } from "./cli/result-shapes.js";
 import { currentCommandContext, resolveCredentials, resolveLoginCredentials, } from "./cli/runtime.js";
+import { suggestSelectors, } from "./cli/selector-suggestions.js";
 import { commandSyntaxTree, commandUsage, } from "./cli/syntax.js";
 import { COMMANDS_RUN_HINT, inferRequiresProject, missingActionError, noCommandError, requireArgs, RESOURCE_NAMES, unknownActionError, unknownFlagError, unknownResourceError, UsageError, } from "./cli/usage.js";
 import { cliVersionResult, } from "./cli/version.js";
@@ -479,7 +480,7 @@ async function validateBatchStep(argv) {
         return { positional, flags, resource, action: metaAction, };
     const resourceActions = commands[resource];
     if (!resourceActions)
-        throw unknownResourceError(resource);
+        throw unknownResourceError(resource, action);
     if (!action) {
         throw missingActionError(resource, Object.keys(resourceActions), `dss ${resource} <action>`);
     }
@@ -766,6 +767,8 @@ async function commandsRunResult(flags) {
         return contract.commandActionSummary();
     }
     const registry = selectors.length === 0 ? contract.buildCommandRegistry() : {};
+    const knownSelectors = [];
+    const unknownSelectors = {};
     for (const selector of selectors) {
         const selectorParts = selector.split(".");
         if (selectorParts.some((part) => part.length === 0)) {
@@ -773,16 +776,62 @@ async function commandsRunResult(flags) {
         }
         const [selectedResource, selectedAction,] = selectorParts;
         const resourceActions = cachedCommandRegistry(selectedResource);
-        if (!resourceActions)
-            throw unknownResourceError(selectedResource);
-        registry[selectedResource] = resourceActions;
-        if (selectedAction && !resourceActions[selectedAction]) {
-            throw unknownActionError(selectedResource, selectedAction, Object.keys(resourceActions));
+        const error = !resourceActions
+            ? unknownResourceError(selectedResource)
+            : selectedAction && !resourceActions[selectedAction]
+                ? unknownActionError(selectedResource, selectedAction, Object.keys(resourceActions))
+                : undefined;
+        if (resourceActions && !error) {
+            registry[selectedResource] = resourceActions;
+            knownSelectors.push(selector);
+            continue;
+        }
+        unknownSelectors[selector] = {
+            error: error,
+            suggestions: suggestSelectors(selector, contract.commandActionSummary()),
+        };
+    }
+    const unknownNames = Object.keys(unknownSelectors);
+    if (unknownNames.length > 0) {
+        if (knownSelectors.length === 0 && selectors.length > 0) {
+            const { error, suggestions, } = unknownSelectors[unknownNames[0]];
+            // The shared error suggests `dss resource action` commands; here the fix is a selector.
+            const hint = suggestions.length === 0
+                ? COMMANDS_RUN_HINT
+                : `Did you mean ${suggestions.map((name) => `\`--fields ${name}\``).join(" or ")}? ${COMMANDS_RUN_HINT}`;
+            const { suggestions: _commandSuggestions, ...details } = error.details ?? {};
+            throw new UsageError(error.message, error.code, hint, {
+                ...details,
+                ...(suggestions.length > 0 ? { suggestions, } : {}),
+            });
         }
+        enqueueCliWarning({
+            code: "unknown_fields",
+            fields: unknownNames,
+            suggestions: Object.fromEntries(unknownNames.flatMap((name) => unknownSelectors[name].suggestions.length > 0
+                ? [[name, unknownSelectors[name].suggestions,],]
+                : [])),
+            hint: "Unknown selectors were skipped; the result holds the known ones. Run `dss commands run` for resource/action names.",
+        });
+    }
+    // On stdout a bare RESOURCE selector lists its actions (usage, description, side effect):
+    // the full entries (flags, schemas, examples) run 30-55 KB per resource, more than an agent
+    // can read in one result. RESOURCE.ACTION and --output keep the full entries.
+    const fullSelectors = typeof outputPath === "string"
+        ? knownSelectors
+        : knownSelectors.filter((selector) => selector.includes("."));
+    const selectedRegistry = selectors.length === 0 ? registry : {};
+    if (fullSelectors.length > 0) {
+        Object.assign(selectedRegistry, projectResultFields(registry, fullSelectors, () => Object.keys(contract.commandActionSummary()).sort()));
+    }
+    for (const resource of knownSelectors) {
+        if (fullSelectors.includes(resource))
+            continue;
+        selectedRegistry[resource] = Object.fromEntries(Object.entries(registry[resource]).map(([action, entry,]) => [
+            action,
+            { usage: entry.usage, description: entry.description, sideEffect: entry.sideEffect, },
+        ]));
     }
-    const selectedRegistry = selectors.length === 0
-        ? registry
-        : projectResultFields(registry, selectors, () => Object.keys(contract.commandActionSummary()).sort());
     if (typeof outputPath === "string") {
         const exported = selectedRegistry;
         await Bun.write(outputPath, `${JSON.stringify(exported)}\n`);
@@ -1046,7 +1095,7 @@ async function runBatch(flags) {
             else {
                 const resourceActions = commands[resource];
                 if (!resourceActions)
-                    throw unknownResourceError(resource);
+                    throw unknownResourceError(resource, action);
                 if (!action) {
                     throw missingActionError(resource, Object.keys(resourceActions), `dss ${resource} <action>`);
                 }
@@ -1461,7 +1510,7 @@ function buildErrorReport(err, contextOverride) {
 }
 function writeErrorReport(err) {
     flushCliWarnings();
-    process.stdout.write(`${JSON.stringify(buildErrorReport(err))}\n`);
+    process.stdout.write(stdoutJson(buildErrorReport(err)));
 }
 /** Only ambiguous mutation failures require full contract metadata. */
 function errorReportNeedsCommandRuntime(err) {
@@ -1509,7 +1558,7 @@ async function main() {
     }
     // Resource and action recovery require only this resource's definitions.
     if (!RESOURCE_NAMES.includes(resource))
-        throw unknownResourceError(resource);
+        throw unknownResourceError(resource, positional[1]);
     const resourceActions = commands[resource];
     if (positional.length === 1) {
         throw missingActionError(resource, Object.keys(resourceActions), `dss ${resource} <action> [args...]`);

package/dist/src/client.d.ts

@@ -23,6 +23,7 @@ import type { KnowledgeBanksResource } from "./resources/knowledge-banks.js";
 import type { LlmsResource } from "./resources/llms.js";
 import type { MacrosResource } from "./resources/macros.js";
 import type { MeaningsResource } from "./resources/meanings.js";
+import type { MessagingChannelsResource } from "./resources/messaging-channels.js";
 import type { MetricsResource } from "./resources/metrics.js";
 import type { MlTasksResource } from "./resources/ml-tasks.js";
 import type { MlflowExtensionResource } from "./resources/mlflow-extension.js";
@@ -196,6 +197,7 @@ export declare class DataikuClient {
     private workspacesResource?;
     private metricsResource?;
     private meaningsResource?;
+    private messagingChannelsResource?;
     private analysesResource?;
     private mlTasksResource?;
     private savedModelsResource?;
@@ -242,6 +244,7 @@ export declare class DataikuClient {
     get workspaces(): WorkspacesResource;
     get metrics(): MetricsResource;
     get meanings(): MeaningsResource;
+    get messagingChannels(): MessagingChannelsResource;
     get analyses(): AnalysesResource;
     get mlTasks(): MlTasksResource;
     get savedModels(): SavedModelsResource;
@@ -301,7 +304,7 @@ export declare class DataikuClient {
      * 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 request timeout applies per received chunk (a stall
-     * deadline), not to the whole transfer.
+     * deadline); the whole transfer is capped at 10x the request timeout.
      */
     getTextTailLimited(path: string, maxBytes: number): Promise<{
         text: string;
@@ -346,6 +349,14 @@ export declare class DataikuClient {
      * boundary is set correctly.
      */
     uploadForm<T = unknown>(path: string, parts: UploadFormPart[], query?: URLSearchParams): Promise<T>;
+    /**
+     * POST a multipart/form-data body like {@link uploadForm} for endpoints whose
+     * success carries no JSON the caller needs (e.g. mail sends): the response
+     * body is not parsed, so a non-JSON acknowledgement cannot turn an already
+     * applied write into a client error.
+     */
+    uploadFormVoid(path: string, parts: UploadFormPart[], query?: URLSearchParams): Promise<void>;
+    private postFormData;
     private uploadResponse;
     upload(path: string, filePath: string, fileName?: string): Promise<void>;
     uploadJson<T>(path: string, filePath: string, fileName?: string): Promise<T>;
@@ -394,9 +405,10 @@ export declare class DataikuClient {
      * 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.
+     * streaming path: a body that stops sending for longer than the timeout
+     * fails with the body-read timeout error. A total budget of
+     * {@link TAIL_READ_TOTAL_BUDGET_FACTOR} x the request timeout bounds a body
+     * that keeps trickling, with an error naming that limit.
      */
     private readBodyTextTail;
     private buildResponseTooLargeError;