dataiku-sdk 0.9.0 → 0.10.0

package/README.md

@@ -8,21 +8,22 @@ Examples below assume the installed `dss` binary. From this checkout, use `./bin
 ## CLI contract
 
 - Success: stdout contains one JSON result.
-- Failure: stderr contains one JSON error envelope with `ok:false`, `error`, `code`, and `exitCode`.
-- `--verbose` may add HTTP trace lines to stderr.
+- Failure: stderr contains one JSONL error event with `type:"error"`, `ok:false`, `error`, `code`, and `exitCode`.
+- Non-fatal diagnostics and `--verbose` traces are JSONL stderr events (`type:"warning"` / `type:"trace"`); no prose trace lines are part of the contract.
 - `--fields a,b,c` projects those fields from an object or array-of-objects result; dotted paths (`a.b.c`) drill into nested objects, and missing fields become `null`; string and scalar results pass through unchanged.
 - No prompts, help screens, tables, banners, or prose output are part of the contract.
 - Exit codes: `0` success, `1` usage/configuration error, `2` DSS/internal error, `3` transient DSS error, `4` completed command with failed long-running DSS work.
 - The exit code is the success signal: chain mutations with `&&` and never infer success from piped output that discards the exit code (e.g. `dss ... 2>&1 | helper; echo done` reports success even when the command failed).
 - `--raw` is only for recipe payload commands. Without `--output`, stdout is raw bytes; with `--output PATH`, stdout is the JSON string equal to `PATH` and the file contains the exact raw bytes.
 
-Discover the complete machine-readable command surface:
+Discover the agent protocol and complete machine-readable command surface:
 
 ```bash
+dss agent contract
 dss commands run
 ```
 
-Agents should parse `commands run` before choosing syntax; inspect `flags`, `requiresAuth`, `requiresProject`, `sideEffect`, and `outputShape` instead of guessing.
+Agents should parse `agent contract` once for protocol/schema compatibility, then parse `commands run` before choosing syntax; inspect `flags`, `structuredExamples`, `schemas`, `requiresAuth`, `requiresProject`, `sideEffect`, `unsafeOutputs`, and `outputShape` instead of guessing.
 
 ## Agent skill installation
 

package/dist/src/cli.js

@@ -72,6 +72,9 @@ function gitRevision(packageRoot) {
 const PACKAGE_ROOT = findPackageRoot();
 const CLI_VERSION = packageVersion(PACKAGE_ROOT);
 const CLI_GIT_REVISION = gitRevision(PACKAGE_ROOT);
+const AGENT_CONTRACT_VERSION = 1;
+const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v1.json";
 function cliVersionResult() {
     return { version: CLI_VERSION, gitRevision: CLI_GIT_REVISION ?? null, };
 }
@@ -1128,13 +1131,13 @@ let pendingCliWarnings = [];
 function enqueueCliWarning(warning) {
     pendingCliWarnings.push(warning);
 }
-/** Emit queued warnings as a single `{ warnings: [...] }` object on stderr. Idempotent. */
+/** Emit queued warnings as one JSONL warning event on stderr. Idempotent. */
 function flushCliWarnings() {
     if (pendingCliWarnings.length === 0)
         return;
     const warnings = pendingCliWarnings;
     pendingCliWarnings = [];
-    process.stderr.write(`${JSON.stringify({ warnings, }, null, 2)}\n`);
+    process.stderr.write(`${JSON.stringify({ type: "warning", warnings, })}\n`);
 }
 function resolveFieldPath(source, field) {
     let current = source;
@@ -1499,6 +1502,7 @@ const BOOLEAN_FLAGS = new Set([
     "errors-only",
     "keep",
     "full-log",
+    "drop-data",
 ]);
 const SHORT_FLAGS = {
     v: "verbose",
@@ -1517,6 +1521,12 @@ const FLAG_ALIASES = {
 };
 const VALUE_FLAGS = new Set([
     "fields",
+    "owner",
+    "topic",
+    "reply",
+    "text",
+    "partitions",
+    "since",
     "activity",
     "agent",
     "api-key",
@@ -6473,6 +6483,8 @@ async function runFixtures(flags) {
 const READ_ACTIONS = new Set([
     "cat",
     "contents",
+    "deployment-settings",
+    "deployment-status",
     "diff",
     "download",
     "download-code",
@@ -6508,6 +6520,7 @@ const READ_ACTIONS = new Set([
     "status",
     "rules",
     "settings",
+    "settings-get",
     "status-by-partition",
     "usages",
 ]);
@@ -6539,6 +6552,9 @@ const AUTHENTICATED_AGENT_FLAGS = [
 const COMMANDS_USAGE = "dss commands run [--json]";
 const COMMANDS_DESCRIPTION = "Print the machine-readable command registry for agent planning.";
 const COMMANDS_EXAMPLES = ["dss commands run", "dss commands run --json",];
+const AGENT_CONTRACT_USAGE = "dss agent contract";
+const AGENT_CONTRACT_DESCRIPTION = "Print the versioned JSON contract agents should use to drive dss.";
+const AGENT_CONTRACT_EXAMPLES = ["dss agent contract",];
 const VERSION_USAGE = "dss version";
 const VERSION_DESCRIPTION = "Print the CLI version and git revision as JSON.";
 const VERSION_EXAMPLES = ["dss version", "dss --version",];
@@ -6585,6 +6601,118 @@ function flagKind(name) {
 function registryKey(resource, action) {
     return `${resource}.${action}`;
 }
+function splitShellLike(input) {
+    const tokens = [];
+    let current = "";
+    let quote;
+    for (let index = 0; index < input.length; index++) {
+        const char = input[index];
+        if (quote) {
+            if (char === quote) {
+                quote = undefined;
+            }
+            else if (char === "\\" && quote === '"' && index + 1 < input.length) {
+                current += input[++index];
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        if (char === "|" || char === "<" || char === ">" || char === ";" || char === "&") {
+            return undefined;
+        }
+        current += char;
+    }
+    if (quote)
+        return undefined;
+    if (current.length > 0)
+        tokens.push(current);
+    return tokens;
+}
+function exampleArgv(example) {
+    const tokens = splitShellLike(example);
+    if (!tokens || tokens[0] !== "dss")
+        return undefined;
+    return tokens.slice(1);
+}
+function structuredExamples(examples, examplePayload) {
+    return (examples ?? []).map((shell) => {
+        const argv = exampleArgv(shell);
+        return {
+            shell,
+            ...(argv ? { argv, } : {}),
+            ...(examplePayload !== undefined && shell.includes("--data")
+                ? { payload: examplePayload, }
+                : {}),
+        };
+    });
+}
+function outputJsonSchema(shape) {
+    if (shape === "array")
+        return { type: "array", items: true, };
+    if (shape === "string")
+        return { type: "string", };
+    return { type: "object", additionalProperties: true, };
+}
+function payloadJsonSchema(payloadSchema) {
+    if (!payloadSchema)
+        return undefined;
+    return payloadSchema.jsonShape === "array"
+        ? { type: "array", items: true, }
+        : { type: "object", additionalProperties: true, };
+}
+function argvJsonSchema(resource, action, _flags, _positionals, _requiredFlags, _requiredOneOf) {
+    return {
+        type: "object",
+        additionalProperties: true,
+        required: ["argv",],
+        properties: {
+            argv: { type: "array", items: { type: "string", }, minItems: 1, },
+            resource: { const: resource, },
+            action: { const: action, },
+        },
+    };
+}
+function unsafeOutputs(resource, action, flags, producesLocalFile) {
+    const outputs = [];
+    if (flags.some((flag) => flag.name === "raw")) {
+        outputs.push({
+            condition: "--raw without --output",
+            kind: "raw-stdout",
+            detail: `${resource} ${action} can intentionally write raw payload bytes/text instead of JSON.`,
+            safeAlternative: flags.some((flag) => flag.name === "output")
+                ? "Pass --output PATH so stdout remains a JSON string containing the path."
+                : "Omit --raw when a JSON stdout value is required.",
+        });
+    }
+    if (producesLocalFile) {
+        outputs.push({
+            condition: "--output or --output-file",
+            kind: "local-file",
+            detail: "Command writes bytes to a local path and returns JSON metadata on stdout.",
+        });
+    }
+    return outputs.length > 0 ? outputs : undefined;
+}
+function buildCommandSchemas(resource, action, flags, positionals, requiredFlags, requiredOneOf, payloadSchema, outputShape) {
+    return {
+        argv: argvJsonSchema(resource, action, flags, positionals, requiredFlags, requiredOneOf),
+        ...(payloadSchema ? { input: payloadJsonSchema(payloadSchema), } : {}),
+        output: outputJsonSchema(outputShape),
+    };
+}
 const EXPLICIT_REGISTRY_OVERRIDES = {
     "dashboard.create": {
         examplePayload: { pages: [], },
@@ -6640,7 +6768,8 @@ function extractPositionals(usage) {
 function inferSideEffect(resource, action) {
     if (resource === "auth")
         return "auth";
-    if (resource === "doctor" || resource === "commands" || resource === "fixtures"
+    if (resource === "agent" || resource === "doctor" || resource === "commands"
+        || resource === "fixtures"
         || resource === "version") {
         return "read";
     }
@@ -6650,20 +6779,23 @@ function inferSideEffect(resource, action) {
         return "write";
     if (READ_ACTIONS.has(action))
         return "read";
-    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove|publish|activate|deploy|import|export|preload|upgrade|stop|restart|duplicate|put|rename|reply|compute)/
-        .test(action)) {
+    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove|publish|activate|deploy|import|export|preload|upgrade|start|stop|restart|duplicate|put|rename|reply|compute|organize)/
+        .test(action)
+        // Compound actions whose mutating verb is a suffix (e.g. permissions-set, dataset-compute).
+        || /-(set|compute)$/.test(action)) {
         return "write";
     }
     return "read";
 }
 function inferRequiresAuth(resource) {
-    return resource !== "auth"
+    return resource !== "agent"
+        && resource !== "auth"
         && resource !== "commands"
         && resource !== "install-skill"
         && resource !== "version";
 }
 function inferRequiresProject(resource, action, usage) {
-    if (resource === "auth" || resource === "doctor" || resource === "commands"
+    if (resource === "agent" || resource === "auth" || resource === "doctor" || resource === "commands"
         || resource === "install-skill" || resource === "version") {
         return false;
     }
@@ -6681,6 +6813,7 @@ const ARRAY_OUTPUT_ACTIONS = new Set([
     "list",
     "list-jupyter",
     "list-sql",
+    "project-timeline",
     "rules",
     "schemas",
     "sessions-jupyter",
@@ -6696,14 +6829,19 @@ const STRING_OUTPUT_ACTIONS = new Set([
     "log-url",
 ]);
 function inferOutputShape(resource, action) {
-    if (resource === "auth" || resource === "commands" || resource === "install-skill"
+    if (resource === "agent" || resource === "auth" || resource === "commands"
+        || resource === "install-skill"
         || resource === "version") {
         return "object";
     }
+    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";
@@ -6936,47 +7074,58 @@ function buildRegistryEntry(resource, action, meta) {
     const cleanupCommand = meta.cleanupCommand
         ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.cleanupCommand
         ?? cleanupCommandFromDeleteUsage(resource, action);
+    const flagMetadata = flags.map((name) => {
+        const kind = flagKind(name);
+        if (kind === "boolean")
+            return { name, kind, };
+        const hint = valueHints.get(name) ?? GLOBAL_FLAG_VALUE_HINTS[name];
+        if (!hint)
+            return { name, kind, };
+        return {
+            name,
+            kind,
+            valueType: hint.valueType,
+            ...(hint.enumValues ? { enumValues: hint.enumValues, } : {}),
+        };
+    });
+    const positionals = extractPositionals(meta.usage);
+    const outputShape = inferOutputShape(resource, action);
+    const producesLocalFile = meta.usage.includes("--output PATH")
+        || meta.usage.includes("--output-file PATH");
+    const uniqueRequiredFlags = uniqueStrings(requiredFlags);
+    const uniqueOptionalFlags = uniqueStrings(optionalFlags);
+    const unsafe = unsafeOutputs(resource, action, flagMetadata, producesLocalFile);
     return {
         resource,
         action,
         usage: meta.usage,
         description: meta.description,
         examples: meta.examples,
-        flags: flags.map((name) => {
-            const kind = flagKind(name);
-            if (kind === "boolean")
-                return { name, kind, };
-            const hint = valueHints.get(name) ?? GLOBAL_FLAG_VALUE_HINTS[name];
-            if (!hint)
-                return { name, kind, };
-            return {
-                name,
-                kind,
-                valueType: hint.valueType,
-                ...(hint.enumValues ? { enumValues: hint.enumValues, } : {}),
-            };
-        }),
-        positionals: extractPositionals(meta.usage),
+        structuredExamples: structuredExamples(meta.examples, examplePayload),
+        flags: flagMetadata,
+        positionals,
         sideEffect,
         requiresAuth,
         requiresProject,
-        outputShape: inferOutputShape(resource, action),
+        outputShape,
         inputContract,
         destructive,
-        producesLocalFile: meta.usage.includes("--output PATH")
-            || meta.usage.includes("--output-file PATH"),
+        producesLocalFile,
         mutatesDss,
         async: asyncKind,
         idempotency: inferIdempotency(sideEffect, action, meta.usage),
         dryRun: meta.usage.includes("--dry-run"),
-        requiredFlags: uniqueStrings(requiredFlags),
-        optionalFlags: uniqueStrings(optionalFlags),
+        requiredFlags: uniqueRequiredFlags,
+        optionalFlags: uniqueOptionalFlags,
         ...(requiredOneOf.length > 0 ? { requiredOneOf, } : {}),
         ...(payloadSchema ? { payloadSchema, } : {}),
+        schemas: buildCommandSchemas(resource, action, flagMetadata, positionals, uniqueRequiredFlags, requiredOneOf, payloadSchema, outputShape),
+        ...(unsafe ? { unsafeOutputs: unsafe, } : {}),
         ...(examplePayload !== undefined ? { examplePayload, } : {}),
         ...(cleanupCommand ? { cleanupCommand, } : {}),
         exitCodes: inferExitCodes(asyncKind),
         ...(cleanupHint ? { cleanupHint, } : {}),
+        agentContractVersion: AGENT_CONTRACT_VERSION,
     };
 }
 function buildCommandRegistry() {
@@ -6995,6 +7144,14 @@ function buildCommandRegistry() {
             examples: COMMANDS_EXAMPLES,
         }),
     };
+    registry.agent = {
+        contract: buildRegistryEntry("agent", "contract", {
+            handler: async () => undefined,
+            usage: AGENT_CONTRACT_USAGE,
+            description: AGENT_CONTRACT_DESCRIPTION,
+            examples: AGENT_CONTRACT_EXAMPLES,
+        }),
+    };
     registry.version = {
         run: buildRegistryEntry("version", "run", {
             handler: async () => undefined,
@@ -7049,6 +7206,191 @@ function buildCommandRegistry() {
     }
     return registry;
 }
+function commandFlagJsonSchema() {
+    return {
+        type: "object",
+        required: ["name", "kind",],
+        additionalProperties: false,
+        properties: {
+            name: { type: "string", },
+            kind: { enum: ["boolean", "value",], },
+            valueType: { type: "string", },
+            enumValues: { type: "array", items: { type: "string", }, },
+        },
+    };
+}
+function commandRegistryEntryJsonSchema() {
+    return {
+        type: "object",
+        required: [
+            "resource",
+            "action",
+            "usage",
+            "flags",
+            "positionals",
+            "sideEffect",
+            "requiresAuth",
+            "requiresProject",
+            "outputShape",
+            "inputContract",
+            "schemas",
+            "exitCodes",
+            "agentContractVersion",
+        ],
+        additionalProperties: true,
+        properties: {
+            resource: { type: "string", },
+            action: { type: "string", },
+            usage: { type: "string", },
+            description: { type: "string", },
+            examples: { type: "array", items: { type: "string", }, },
+            structuredExamples: { type: "array", items: { type: "object", additionalProperties: true, }, },
+            flags: { type: "array", items: commandFlagJsonSchema(), },
+            positionals: { type: "array", items: { type: "string", }, },
+            sideEffect: { enum: ["read", "write", "auth",], },
+            requiresAuth: { type: "boolean", },
+            requiresProject: { type: "boolean", },
+            outputShape: { enum: ["object", "array", "string", "void",], },
+            inputContract: { type: "object", additionalProperties: { type: "boolean", }, },
+            destructive: { enum: ["none", "reversible", "destructive",], },
+            producesLocalFile: { type: "boolean", },
+            mutatesDss: { type: "boolean", },
+            async: { enum: ["none", "job", "future",], },
+            idempotency: { enum: ["safe", "convergent", "if-not-exists", "if-exists", "none",], },
+            dryRun: { type: "boolean", },
+            requiredFlags: { type: "array", items: { type: "string", }, },
+            optionalFlags: { type: "array", items: { type: "string", }, },
+            schemas: { type: "object", additionalProperties: true, },
+            unsafeOutputs: { type: "array", items: { type: "object", additionalProperties: true, }, },
+            exitCodes: { type: "object", additionalProperties: { type: "number", }, },
+            agentContractVersion: { const: AGENT_CONTRACT_VERSION, },
+        },
+    };
+}
+function commandRegistryJsonSchema() {
+    return {
+        $schema: JSON_SCHEMA_DRAFT,
+        type: "object",
+        additionalProperties: {
+            type: "object",
+            additionalProperties: commandRegistryEntryJsonSchema(),
+        },
+    };
+}
+function errorEnvelopeJsonSchema() {
+    return {
+        type: "object",
+        required: ["type", "ok", "error", "code", "category", "exitCode",],
+        additionalProperties: true,
+        properties: {
+            type: { const: "error", },
+            ok: { const: false, },
+            error: { type: "string", },
+            code: { type: "string", },
+            category: { enum: ["usage", "dss", "internal",], },
+            exitCode: { type: "number", },
+            resource: { type: "string", },
+            action: { type: "string", },
+            projectKey: { type: "string", },
+        },
+    };
+}
+function warningEventJsonSchema() {
+    return {
+        type: "object",
+        required: ["type", "warnings",],
+        additionalProperties: false,
+        properties: {
+            type: { const: "warning", },
+            warnings: { type: "array", items: { type: "object", additionalProperties: true, }, },
+        },
+    };
+}
+function traceEventJsonSchema() {
+    return {
+        type: "object",
+        required: ["type", "phase", "method", "url", "attempt", "maxAttempts",],
+        additionalProperties: false,
+        properties: {
+            type: { const: "trace", },
+            phase: { enum: ["request", "response", "error",], },
+            method: { type: "string", },
+            url: { type: "string", },
+            attempt: { type: "number", },
+            maxAttempts: { type: "number", },
+            status: { type: "number", },
+            elapsedMs: { type: "number", },
+            detail: { type: "string", },
+        },
+    };
+}
+function agentContractJsonSchema() {
+    return {
+        $schema: JSON_SCHEMA_DRAFT,
+        $id: AGENT_CONTRACT_SCHEMA_ID,
+        type: "object",
+        required: ["protocol", "agentContractVersion", "cli", "commands", "schemas", "stdio",],
+        additionalProperties: true,
+        properties: {
+            protocol: { const: "dataiku-sdk-agent", },
+            agentContractVersion: { const: AGENT_CONTRACT_VERSION, },
+            cli: { type: "object", additionalProperties: true, },
+            commands: { type: "object", additionalProperties: true, },
+            schemas: { type: "object", additionalProperties: true, },
+            stdio: { type: "object", additionalProperties: true, },
+        },
+    };
+}
+function commandActionSummary(registry) {
+    const summary = {};
+    for (const [resource, actions,] of Object.entries(registry)) {
+        summary[resource] = Object.keys(actions).sort();
+    }
+    return summary;
+}
+function buildAgentContract() {
+    const registry = buildCommandRegistry();
+    return {
+        protocol: "dataiku-sdk-agent",
+        agentContractVersion: AGENT_CONTRACT_VERSION,
+        cli: cliVersionResult(),
+        commands: {
+            discoveryCommand: "dss commands run",
+            actions: commandActionSummary(registry),
+        },
+        schemas: {
+            agentContract: agentContractJsonSchema(),
+            commandRegistry: commandRegistryJsonSchema(),
+            commandRegistryEntry: commandRegistryEntryJsonSchema(),
+            errorEnvelope: errorEnvelopeJsonSchema(),
+            warningEvent: warningEventJsonSchema(),
+            traceEvent: traceEventJsonSchema(),
+        },
+        stdio: {
+            stdout: {
+                success: "single-json-value",
+                rawEscapeHatches: [
+                    "recipe get-payload --raw without --output",
+                    "recipe cat --raw without --output",
+                ],
+            },
+            stderr: {
+                format: "jsonl",
+                events: ["warning", "trace", "error",],
+                error: "single-final-error-event-on-nonzero-exit",
+            },
+        },
+        planning: {
+            discoveryCommand: "dss commands run",
+            contractCommand: AGENT_CONTRACT_USAGE,
+            mutatingCommandsAdvertisePlan: true,
+        },
+        compatibility: {
+            fieldsAreAdditiveWithinMajor: true,
+            failFastWhenUnsupported: "Check agentContractVersion before planning commands.",
+        },
+    };
+}
 function exitCodesOnFailure(entry) {
     return {
         usage: entry.exitCodes.usage,
@@ -7609,6 +7951,31 @@ function commandPlanShape(resource, action, args, flags, entry, projectKey) {
                 identifiers: { id, cellId: flags["cell-id"], },
                 payload: { retain: num(flags["retain"]), },
             };
+        case "project.permissions-set":
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint("/permissions"),
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "continuous-activity.start":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/continuous-activities/${encodeURIComponent(id)}/start`),
+                identifiers: { recipeId: id, },
+                payload: jsonInput(flags) ?? {},
+            };
+        case "metrics.dataset-compute":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/datasets/${encodeURIComponent(id)}/actions/computeMetrics?partition=`),
+                identifiers: { dataset: id, },
+            };
+        case "flow-zone.organize":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/flow/zones"),
+                payload: jsonInput(flags),
+            };
         default:
             return {
                 method: action.startsWith("delete") || action === "abort" ? "DELETE" : "POST",
@@ -7958,6 +8325,7 @@ function buildErrorReport(err) {
     const exitCode = errorExitCode(err);
     if (err instanceof UsageError) {
         return {
+            type: "error",
             ok: false,
             error: err.message,
             code: err.code,
@@ -7970,6 +8338,7 @@ function buildErrorReport(err) {
     }
     if (err instanceof CommandResultFailure) {
         return {
+            type: "error",
             ok: false,
             error: err.message,
             code: "long_running_failure",
@@ -7981,6 +8350,7 @@ function buildErrorReport(err) {
     }
     if (err instanceof DataikuError) {
         return {
+            type: "error",
             ok: false,
             error: err.message,
             code: dataikuErrorCode(err.category),
@@ -8001,6 +8371,7 @@ function buildErrorReport(err) {
     }
     const message = err instanceof Error ? err.message : String(err);
     return {
+        type: "error",
         ok: false,
         error: message,
         code: "internal_error",
@@ -8010,7 +8381,7 @@ function buildErrorReport(err) {
     };
 }
 function writeErrorReport(err) {
-    process.stderr.write(`${JSON.stringify(buildErrorReport(err), null, 2)}\n`);
+    process.stderr.write(`${JSON.stringify(buildErrorReport(err))}\n`);
 }
 // ---------------------------------------------------------------------------
 // Main
@@ -8122,6 +8493,16 @@ async function main() {
         });
         return;
     }
+    if (resource === "agent") {
+        const action = positional[1];
+        if (!action)
+            throw missingActionError("agent", ["contract",], AGENT_CONTRACT_USAGE);
+        currentCommandContext.action = action;
+        if (action !== "contract")
+            throw unknownActionError("agent", action, ["contract",]);
+        writeCommandResult(buildAgentContract());
+        return;
+    }
     if (resource === "commands") {
         const action = positional[1];
         if (!action)

package/dist/src/client.d.ts

@@ -29,6 +29,17 @@ import { VariablesResource } from "./resources/variables.js";
 import { WebappsResource } from "./resources/webapps.js";
 import { WikiResource } from "./resources/wiki.js";
 import { WorkspacesResource } from "./resources/workspaces.js";
+export interface DataikuClientTraceEvent {
+    type: "trace";
+    phase: "request" | "response" | "error";
+    method: string;
+    url: string;
+    attempt: number;
+    maxAttempts: number;
+    status?: number;
+    elapsedMs?: number;
+    detail?: string;
+}
 export interface DataikuClientConfig {
     /** DSS base URL (e.g. https://dss.example.com) */
     url: string;
@@ -40,8 +51,9 @@ export interface DataikuClientConfig {
     requestTimeoutMs?: number;
     /** Max retry attempts for idempotent requests (default 4, capped at 10) */
     retryMaxAttempts?: number;
-    /** Emit HTTP request/response logs to stderr for CLI debugging. */
+    /** Emit HTTP request/response trace events. Defaults to JSONL on stderr when verbose is true. */
     verbose?: boolean;
+    onTrace?: (event: DataikuClientTraceEvent) => void;
     /** Override TLS certificate verification for HTTPS requests. */
     tlsRejectUnauthorized?: boolean;
     /** Extra PEM CA bundle to trust in addition to Bun's default trust store. */
@@ -62,6 +74,7 @@ export declare class DataikuClient {
     private readonly retryMaxAttempts;
     private readonly verbose;
     private readonly tlsOptions;
+    private readonly onTrace;
     private readonly onValidationWarning;
     private projectsResource?;
     private datasetsResource?;
@@ -143,7 +156,7 @@ export declare class DataikuClient {
     stream(path: string): Promise<Response>;
     private getHeaders;
     private getAnyHeaders;
-    private logVerbose;
+    private logTrace;
     /**
      * Validate raw data against a TypeBox schema, throwing on structural mismatch.
      * Resources call this instead of bare `as T` casts for validated responses.

package/dist/src/client.js

@@ -44,6 +44,9 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 /* ------------------------------------------------------------------ */
 /*  Helpers                                                            */
 /* ------------------------------------------------------------------ */
+function defaultTrace(event) {
+    process.stderr.write(`${JSON.stringify(event)}\n`);
+}
 function defaultValidationWarning(_method, _errors) {
 }
 function sleep(ms) {
@@ -139,6 +142,7 @@ export class DataikuClient {
     retryMaxAttempts;
     verbose;
     tlsOptions;
+    onTrace;
     onValidationWarning;
     /* Resource namespaces — lazily initialized to break circular imports */
     projectsResource;
@@ -280,6 +284,7 @@ export class DataikuClient {
         this.retryMaxAttempts = Math.min(Math.max(1, rawMax), MAX_RETRY_ATTEMPTS_CAP);
         this.verbose = config.verbose === true;
         this.tlsOptions = buildFetchTlsOptions(config);
+        this.onTrace = config.onTrace ?? defaultTrace;
         this.onValidationWarning = config.onValidationWarning ?? defaultValidationWarning;
     }
     getRequestTimeoutMs() {
@@ -423,9 +428,9 @@ export class DataikuClient {
             Accept: "*/*",
         };
     }
-    logVerbose(message) {
+    logTrace(event) {
         if (this.verbose)
-            process.stderr.write(`[dss] ${message}\n`);
+            this.onTrace({ type: "trace", ...event, });
     }
     /* ---- public: schema-validated parsing ---- */
     /**
@@ -498,7 +503,7 @@ export class DataikuClient {
                 timedOut = true;
                 controller.abort();
             }, this.requestTimeoutMs);
-            this.logVerbose(`${method} ${url}`);
+            this.logTrace({ phase: "request", method, url, attempt, maxAttempts, });
             try {
                 const requestInit = {
                     ...init,
@@ -508,7 +513,15 @@ export class DataikuClient {
                 if (this.tlsOptions)
                     requestInit.tls = this.tlsOptions;
                 const res = await fetch(url, requestInit);
-                this.logVerbose(`${method} ${url} → ${res.status} (${Date.now() - startedAt}ms)`);
+                this.logTrace({
+                    phase: "response",
+                    method,
+                    url,
+                    attempt,
+                    maxAttempts,
+                    status: res.status,
+                    elapsedMs: Date.now() - startedAt,
+                });
                 if (!res.ok) {
                     const text = await res.text();
                     const canRetry = retryEnabled && attempt < maxAttempts && isTransientError(res.status, text);
@@ -537,7 +550,15 @@ export class DataikuClient {
                     : error instanceof Error
                         ? error.message
                         : "Unknown transport error";
-                this.logVerbose(`${method} ${url} → ERROR (${Date.now() - startedAt}ms) ${detail}`);
+                this.logTrace({
+                    phase: "error",
+                    method,
+                    url,
+                    attempt,
+                    maxAttempts,
+                    elapsedMs: Date.now() - startedAt,
+                    detail,
+                });
                 const statusText = timedOut ? "Request Timeout" : "Network Error";
                 throw new DataikuError(0, statusText, detail, buildRetryMetadata(method, retryEnabled, maxAttempts, attempt, delaysMs, timedOut));
             }

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export { DataikuClient, type DataikuClientConfig, } from "./client.js";
+export { DataikuClient, type DataikuClientConfig, type DataikuClientTraceEvent, } from "./client.js";
 export { type CredentialValidationOptions, type CredentialValidationResult, validateCredentials, } from "./auth.js";
 export { type DssCredentials, getConfigDir, getCredentialsPath, loadCredentials, saveCredentials, } from "./config.js";
 export { DataikuError, type DataikuErrorCategory, type DataikuErrorTaxonomy, type DataikuRetryMetadata, } from "./errors.js";

package/dist/src/skill.js

@@ -11,8 +11,8 @@ If the installed \`dss\` binary is unavailable but the repository checkout is th
 ## Contract
 
 - Success writes exactly one JSON result to stdout.
-- Failure writes exactly one JSON error envelope to stderr with \`ok:false\`, \`error\`, \`code\`, and \`exitCode\`.
-- \`--verbose\` may add HTTP trace lines to stderr.
+- Failure writes exactly one JSONL error event to stderr with \`type:"error"\`, \`ok:false\`, \`error\`, \`code\`, and \`exitCode\`.
+- Non-fatal warnings and \`--verbose\` HTTP traces are JSONL stderr events (\`type:"warning"\` / \`type:"trace"\`), never prose.
 - No prompts, help screens, tables, banners, or prose output are part of the contract.
 - Exit codes: 0 success, 1 usage/configuration error, 2 DSS or internal error, 3 transient/retryable DSS error, 4 completed command with failed long-running DSS work.
 - \`--raw\` is the only stdout escape hatch: recipe payload commands emit raw bytes to stdout unless \`--output PATH\` is also set; with \`--output\`, stdout is the JSON string equal to \`PATH\` and the file receives exact raw bytes.
@@ -21,10 +21,11 @@ If the installed \`dss\` binary is unavailable but the repository checkout is th
 ## Discover commands
 
 \`\`\`bash
+dss agent contract
 dss commands run
 \`\`\`
 
-The registry is the canonical schema for resources, actions, flags, positional arguments, side effects, auth requirements, output shape, idempotency, dry-run support, payload schemas, cleanup hints, and exit codes. Use it before choosing command syntax.
+Use \`dss agent contract\` once to check \`agentContractVersion\`, stderr event schemas, non-JSON escape hatches, and compatibility rules. The command registry from \`dss commands run\` is the canonical schema for resources, actions, flags, positional arguments, side effects, auth requirements, output shape, idempotency, dry-run support, structured examples, payload schemas, unsafe outputs, cleanup hints, and exit codes. Use it before choosing command syntax.
 Credential lookup order is flags first, then \`DATAIKU_*\` environment variables, then saved credentials.
 Set \`DATAIKU_DISABLE_ENV=1\` when a test must ignore both \`.env\` files and \`DATAIKU_*\` environment variables.
 When \`.env\` loading is enabled, the CLI reads \`.env\` from the command's current working directory first and then the CLI build/root directory; the invocation directory wins on conflicting keys. Put test-specific \`.env\` files in the directory where you invoke \`dss\`.
@@ -91,10 +92,11 @@ Mutations print a small JSON ack to stdout and exit 0 on success (e.g. \`{"updat
 
 ## Error envelope
 
-Parse stderr as JSON when exit code is non-zero:
+Parse each stderr line as JSON; on non-zero exit the final line is an error event:
 
 \`\`\`json
 {
+  "type": "error",
   "ok": false,
   "error": "Missing API key.",
   "code": "usage_error",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dataiku-sdk",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Dataiku DSS SDK and CLI for programmatic access to DSS REST APIs",
 	"type": "module",
 	"workspaces": [