deepline 0.1.146 → 0.1.148

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -38,6 +38,8 @@ import type {
   ToolResultTargetAccessor,
   ToolResultTargetMetadata,
 } from './tool-result-types';
+import { createPlayDataset, type PlayDataset } from '../plays/dataset';
+import { normalizeTableNamespace, sha256Hex } from '../plays/row-identity';
 
 type PathSegment = string | number | '*';
 
@@ -737,12 +739,22 @@ function resolveListRows(
     );
     let resolvedPath: string | null = null;
     let rows: Record<string, unknown>[] | null = null;
+    let emptyMatch: { path: string; rows: Record<string, unknown>[] } | null =
+      null;
     for (const candidate of candidates) {
       rows = normalizeRows(getAtPath(result, candidate));
-      if (rows) {
+      if (!rows) {
+        continue;
+      }
+      if (rows.length > 0) {
         resolvedPath = candidate;
         break;
       }
+      emptyMatch ??= { path: candidate, rows };
+    }
+    if (!rows && emptyMatch) {
+      resolvedPath = emptyMatch.path;
+      rows = emptyMatch.rows;
     }
     if (!rows) continue;
     const storedPath = resolvedPath ?? path;
@@ -751,7 +763,12 @@ function resolveListRows(
       .filter(Boolean)
       .at(-1)
       ?.replace(/\[\d+\]$/, '');
-    lists[name || storedPath] = { path: storedPath, rows };
+    const listName = name || storedPath;
+    const existing = lists[listName];
+    if (existing?.rows.length && rows.length === 0) {
+      continue;
+    }
+    lists[listName] = { path: storedPath, rows };
   }
   return lists;
 }
@@ -935,10 +952,26 @@ function buildExtractedAccessors(
 function buildListAccessors(
   resolved: Record<string, { path: string; rows: Record<string, unknown>[] }>,
   lists: Record<string, ToolResultListMetadata>,
+  toolId: string,
+  executionDiscriminator: string,
 ): Record<string, ToolResultListAccessor> {
   return Object.fromEntries(
     Object.entries(lists).map(([name, metadata]) => {
       const rows = resolved[name]?.rows ?? [];
+      const datasetDiscriminator = `${executionDiscriminator}:${listRowsFingerprint(rows)}`;
+      const dataset = createPlayDataset(rows, {
+        kind: 'csv',
+        sourceLabel: metadata.path,
+        tableNamespace: listTableNamespace(
+          toolId,
+          name,
+          metadata.path,
+          datasetDiscriminator,
+        ),
+        datasetId: `tool-list:${sha256Hex(
+          `${toolId}:${metadata.path}:${datasetDiscriminator}`,
+        )}`,
+      });
       const accessor = {
         path: metadata.path,
         count: metadata.count,
@@ -946,7 +979,7 @@ function buildListAccessors(
       } as ToolResultListAccessor;
       Object.defineProperty(accessor, 'get', {
         value() {
-          return rows;
+          return dataset;
         },
         enumerable: false,
       });
@@ -955,6 +988,44 @@ function buildListAccessors(
   );
 }
 
+function listRowsFingerprint(rows: readonly Record<string, unknown>[]): string {
+  try {
+    return sha256Hex(
+      JSON.stringify(
+        {
+          count: rows.length,
+          rows,
+        },
+        (_key, value) => (typeof value === 'bigint' ? value.toString() : value),
+      ),
+    ).slice(0, 12);
+  } catch {
+    return sha256Hex(String(rows.length)).slice(0, 12);
+  }
+}
+
+function listTableNamespace(
+  toolId: string,
+  name: string,
+  path: string,
+  discriminator: string,
+): string {
+  const raw = `${toolId}_${name || path || 'rows'}_${sha256Hex(discriminator).slice(0, 10)}`;
+  try {
+    return normalizeTableNamespace(raw);
+  } catch {
+    const hash = sha256Hex(raw).slice(0, 10);
+    const leaf = name || path.split('.').filter(Boolean).at(-1) || 'rows';
+    let prefix = 'rows';
+    try {
+      prefix = normalizeTableNamespace(leaf).slice(0, 52) || 'rows';
+    } catch {
+      prefix = 'rows';
+    }
+    return normalizeTableNamespace(`${prefix}_${hash}`);
+  }
+}
+
 export function createToolExecuteResult<TResult = unknown>(input: {
   status: string;
   jobId?: string;
@@ -994,7 +1065,12 @@ export function createToolExecuteResult<TResult = unknown>(input: {
     ...(result.meta ? { meta: result.meta } : {}),
   };
   const extractedValues = buildExtractedAccessors(targets);
-  const extractedLists = buildListAccessors(resolvedLists, lists);
+  const extractedLists = buildListAccessors(
+    resolvedLists,
+    lists,
+    input.metadata.toolId,
+    input.jobId ?? input.execution.cacheKey ?? 'inline',
+  );
   const wrapper = {
     status: input.status,
     ...(input.jobId ? { job_id: input.jobId } : {}),
@@ -1063,7 +1139,7 @@ export function readValue(
 export function readList(
   result: ToolExecuteResult,
   selector?: readonly string[] | string,
-): Record<string, unknown>[] {
+): PlayDataset<Record<string, unknown>> | Record<string, unknown>[] {
   if (selector) {
     const paths = Array.isArray(selector) ? selector : [selector];
     const found = findFirstTargetByPath(resultRootOf(result), paths)?.value;

package/dist/cli/index.js

@@ -619,10 +619,11 @@ var SDK_RELEASE = {
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
   // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
-  version: "0.1.146",
-  apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
+  // 0.1.111 ships dataset-native tool list getters and result row datasets.
+  version: "0.1.148",
+  apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.146",
+    latest: "0.1.148",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -633,52 +634,79 @@ var SDK_RELEASE = {
       },
       {
         command: "plays",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play file commands now use dataset-native list getters and result row datasets."
       },
       {
         command: "plays run",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play run results now promote row-shaped outputs into dataset handles for safe export."
       },
       {
         command: "run",
         displayCommand: "plays run",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play run results now promote row-shaped outputs into dataset handles for safe export."
       },
       {
         command: "plays check",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play file checks now validate dataset-native list getter authoring."
       },
       {
         command: "check",
         displayCommand: "plays check",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play file checks now validate dataset-native list getter authoring."
       },
       {
         command: "plays publish",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Published play artifacts now target dataset-native list getters and result row datasets."
       },
       {
         command: "publish",
         displayCommand: "plays publish",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Published play artifacts now target dataset-native list getters and result row datasets."
       },
       {
         command: "plays set-live",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Published play artifacts now target dataset-native list getters and result row datasets."
       },
       {
         command: "set-live",
         displayCommand: "plays set-live",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Published play artifacts now target dataset-native list getters and result row datasets."
+      },
+      {
+        command: "runs",
+        minimumSupported: "0.1.111",
+        reason: "Run result rows now render as dataset handles with explicit export commands."
+      },
+      {
+        command: "runs get",
+        minimumSupported: "0.1.111",
+        reason: "Run result rows now render as dataset handles with explicit export commands."
+      },
+      {
+        command: "get",
+        displayCommand: "runs get",
+        minimumSupported: "0.1.111",
+        reason: "Run result rows now render as dataset handles with explicit export commands."
+      },
+      {
+        command: "runs export",
+        minimumSupported: "0.1.111",
+        reason: "Run result row datasets now use the dataset-handle export contract."
+      },
+      {
+        command: "export",
+        displayCommand: "runs export",
+        minimumSupported: "0.1.111",
+        reason: "Run result row datasets now use the dataset-handle export contract."
       }
     ],
     autoUpdatePatchLag: 2
@@ -8302,9 +8330,10 @@ function generateProviderSourceBlock(input2) {
     input: ${inputName},
     description: ${jsString(`Seed ${input2.entity} rows from ${input2.provider}.`)},
   });
-  // extractedLists.${getter}.get() returns provider-shaped rows. Do not assume canonical fields;
+  // extractedLists.${getter}.get() returns a dataset handle of provider-shaped rows. Do not assume canonical fields;
   // inspect source_${input2.index}.extractedLists.${getter}.keys or the provider output schema, then map explicitly below.
-  const sourceRows_${input2.index} = ${accessorExpression(`source_${input2.index}.extractedLists`, getter)}.get() as ${input2.collectionType}[];`;
+  const sourceRowsDataset_${input2.index} = ${accessorExpression(`source_${input2.index}.extractedLists`, getter)}.get();
+  const sourceRows_${input2.index} = (await sourceRowsDataset_${input2.index}.peek(limit)) as ${input2.collectionType}[];`;
 }
 function generateProviderSourceRowsBlock(input2) {
   const blocks = input2.source.values.map(
@@ -10990,6 +11019,9 @@ function formatPlayLogLine(line, status, state) {
   }
   return `${prefix}${message}`;
 }
+function isDatasetResultEnvelope(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && value.kind === "dataset";
+}
 function compactReturnValue(value, depth = 0) {
   if (depth >= 4) {
     return value && typeof value === "object" ? "[Object]" : value;
@@ -11001,6 +11033,7 @@ function compactReturnValue(value, depth = 0) {
   if (!value || typeof value !== "object") {
     return value;
   }
+  const isDatasetEnvelope = isDatasetResultEnvelope(value);
   const output2 = {};
   for (const [key, entry] of Object.entries(value)) {
     if (depth === 0 && key === "_metadata") {
@@ -11009,13 +11042,41 @@ function compactReturnValue(value, depth = 0) {
     if (BULKY_RETURN_KEYS.has(key)) {
       continue;
     }
-    if (key === "access") {
+    if (isDatasetEnvelope && key === "access") {
+      continue;
+    }
+    if (isDatasetEnvelope && (key === "queryDatasetCommand" || key === "cliCommand")) {
+      continue;
+    }
+    if (isDatasetEnvelope && key === "slowExportAsCsvCommand") {
+      output2.fullExportCommand = entry;
       continue;
     }
     output2[key] = compactReturnValue(entry, depth + 1);
   }
   return output2;
 }
+function defaultResultForEnvelope(value, depth = 0) {
+  if (depth > 20 || value == null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => defaultResultForEnvelope(entry, depth + 1));
+  }
+  const isDatasetEnvelope = isDatasetResultEnvelope(value);
+  const output2 = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (isDatasetEnvelope && (key === "queryDatasetCommand" || key === "cliCommand")) {
+      continue;
+    }
+    if (isDatasetEnvelope && key === "slowExportAsCsvCommand") {
+      output2.fullExportCommand = entry;
+      continue;
+    }
+    output2[key] = defaultResultForEnvelope(entry, depth + 1);
+  }
+  return output2;
+}
 function formatJsonPreview(value) {
   const json = JSON.stringify(value, null, 2);
   if (!json || json === "{}") {
@@ -11059,9 +11120,6 @@ function collectDatasetHandleLines(value, path = "result", datasetStats) {
     if (datasetStats && (datasetStats.source === path || datasetStats.source === record.path)) {
       lines2.push(...formatDatasetStatsLines(datasetStats.stats, "    "));
     }
-    if (typeof record.queryDatasetCommand === "string") {
-      lines2.push(`  query dataset: ${record.queryDatasetCommand}`);
-    }
     if (typeof record.slowExportAsCsvCommand === "string") {
       lines2.push(`  export CSV: ${record.slowExportAsCsvCommand}`);
     }
@@ -11472,7 +11530,7 @@ function compactPlayStatus(status) {
     logs: normalizeLogsForEnvelope(status),
     ...displayError ? { error: displayError } : {},
     ...warnings.length > 0 ? { warnings } : {},
-    ...result !== void 0 ? { result } : {},
+    ...result !== void 0 ? { result: defaultResultForEnvelope(result) } : {},
     ...billing ? { billing } : {},
     next: buildRunNextCommands(status)
   };
@@ -20415,16 +20473,24 @@ function tryConvertToList(payload, options) {
     (entry) => typeof entry === "string" && entry.trim().length > 0
   ) : [];
   if (listExtractorPaths.length > 0) {
+    let emptyMatch = null;
     for (const root of candidateRoots(payload)) {
       for (const extractorPath of listExtractorPaths) {
         const resolved = getByDottedPath(root.value, extractorPath);
         const rows = normalizeRows(resolved);
-        if (rows && rows.length > 0) {
-          const sourcePath = root.path ? `${root.path}.${extractorPath}` : extractorPath;
+        if (!rows) {
+          continue;
+        }
+        const sourcePath = root.path ? `${root.path}.${extractorPath}` : extractorPath;
+        if (rows.length > 0) {
           return { rows, strategy: "configured_paths", sourcePath };
         }
+        emptyMatch ??= { rows, strategy: "configured_paths", sourcePath };
       }
     }
+    if (emptyMatch) {
+      return emptyMatch;
+    }
   }
   for (const root of candidateRoots(payload)) {
     const candidate = findBestArrayCandidate(root.value, root.path ?? "");
@@ -20448,9 +20514,9 @@ function writeJsonOutputFile(payload, stem) {
   (0, import_node_fs12.writeFileSync)(outputPath, JSON.stringify(payload, null, 2), "utf-8");
   return outputPath;
 }
-function writeCsvOutputFile(rows, stem) {
-  const outputDir = ensureOutputDir();
-  const outputPath = (0, import_node_path14.join)(outputDir, `${stem}_${Date.now()}.csv`);
+function writeCsvOutputFile(rows, stem, options) {
+  const outputPath = options?.outPath ? options.outPath : (0, import_node_path14.join)(ensureOutputDir(), `${stem}_${Date.now()}.csv`);
+  (0, import_node_fs12.mkdirSync)((0, import_node_path14.dirname)(outputPath), { recursive: true });
   const seen = /* @__PURE__ */ new Set();
   const columns = [];
   for (const row of rows) {
@@ -20979,6 +21045,7 @@ Examples:
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
   deepline tools execute hunter_email_verifier -p email=a@b.com
   deepline tools execute test_rate_limit --input '{"key":"smoke"}' --json | jq '.status'
+  deepline tools execute free_simple_company_search --input '{"sql":"SELECT company_name FROM companies LIMIT 10"}' --out companies.csv
 `
   ).option(
     "-p, --param <key=value>",
@@ -21000,6 +21067,9 @@ Examples:
   ).option(
     "--output-format <format>",
     "Output format: auto, csv, csv_file, json, or json_file"
+  ).option(
+    "-o, --out <path>",
+    "Write row-shaped tool output to this CSV path"
   ).option(
     "--no-preview",
     "Only print the extracted output path when applicable"
@@ -21012,6 +21082,7 @@ Examples:
       ...options.input ? ["--input", options.input] : [],
       ...options.payload ? ["--payload", options.payload] : [],
       ...options.outputFormat ? ["--output-format", options.outputFormat] : [],
+      ...options.out ? ["--out", options.out] : [],
       ...options.preview === false ? ["--no-preview"] : []
     ];
     process.exitCode = await executeTool(args);
@@ -21462,7 +21533,7 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
       invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter.",
       observeActualShape: observedOutputCommand,
       observedOutput: observedOutputCommand,
-      forPlayGetterBugs: "Run a tiny play, inspect `deepline runs get <run-id> --full --json`, and export returned dataset handles with `deepline runs export`. Backing tables exist only for ctx.map(...).run(...) stages that actually executed.",
+      forPlayGetterBugs: "Run a tiny play, inspect returned handles with `deepline runs get <run-id> --full --json`, then export row datasets with `deepline runs export`.",
       executeOutputFields: "tools execute JSON may include output_preview for this direct probe only; play debugging uses run output and returned dataset handles."
     },
     ...starterScript ? { starterScript } : {}
@@ -21669,12 +21740,13 @@ function parseExecuteOptions(args) {
   const toolId = args[0];
   if (!toolId) {
     throw new Error(
-      `Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--no-preview]`
+      `Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--out rows.csv] [--output-format auto|csv|csv_file|json|json_file] [--no-preview]`
     );
   }
   const params = {};
   let outputFormat = "auto";
   let noPreview = false;
+  let outPath = null;
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if ((arg === "--param" || arg === "-p") && args[index + 1]) {
@@ -21706,9 +21778,13 @@ function parseExecuteOptions(args) {
       noPreview = true;
       continue;
     }
+    if ((arg === "--out" || arg === "-o") && args[index + 1]) {
+      outPath = (0, import_node_path15.resolve)(args[++index]);
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
-  return { toolId, params, outputFormat, noPreview };
+  return { toolId, params, outputFormat, noPreview, outPath };
 }
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
@@ -21752,9 +21828,14 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   });
 
   const list = Object.values(result.extractedLists)[0];
-  const rows = (list?.get() ?? []).slice(0, 100);
+  if (!list) {
+    throw new Error('Expected ${input2.toolId} to expose an extracted list getter.');
+  }
+  const rows = list.get();
   // ${sampleRows}
   // columns: ${columns}
+  // extractedLists.<name>.get() returns a dataset handle for row-shaped list outputs.
+  // Pass it to ctx.dataset; use rows.peek/count/materialize only for deliberate bounded inspection.
   // .withColumn('email_waterfall', (row, rowCtx) => rowCtx.runPlay('name_domain_email', 'name-and-domain-to-email', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), domain: String(row.domain ?? '') }, { description: 'Resolve email.' }))
   // .withColumn('phone_waterfall', (row, rowCtx) => rowCtx.runPlay('contact_phone', 'contact-to-phone', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), email: String(row.email ?? '') }, { description: 'Resolve phone.' }))
   // ctx.dataset is idempotent by dataset key + row key; reruns reuse completed rows.
@@ -21814,7 +21895,7 @@ function buildToolExecuteBaseEnvelope(input2) {
     ...summaryEntries.length > 0 ? { summary: input2.summary } : {},
     next: {
       inspect: inspectCommand,
-      playDebugging: "When fixing a play getter, inspect the actual play run table with runs get / inspect rows; do not copy CLI preview paths blindly.",
+      playDebugging: "When fixing a play getter, inspect returned dataset handles with runs get and export rows with runs export; do not copy CLI preview paths blindly.",
       ...input2.listConversion ? {
         expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again.",
         listSourcePath: input2.listConversion.sourcePath ?? "auto-detected list in the CLI response preview"
@@ -21826,7 +21907,7 @@ function buildToolExecuteBaseEnvelope(input2) {
           title: "output",
           lines: [
             `${input2.listConversion.rows.length} row(s) extracted from ${input2.listConversion.sourcePath ?? "auto-detected list"}`,
-            "paths above are observed from this execute response; use run table rows to debug play getters",
+            "paths above are observed from this execute response; use runs get and runs export to validate play output",
             `columns: ${JSON.stringify(Object.keys(input2.listConversion.rows[0] ?? {}))}`,
             `preview: ${JSON.stringify(input2.listConversion.rows.slice(0, 5))}`
           ]
@@ -21906,7 +21987,7 @@ async function executeTool(args) {
     listConversion,
     summary
   });
-  if (parsed.outputFormat === "json" || parsed.outputFormat === "auto" && shouldEmitJson()) {
+  if (!parsed.outPath && (parsed.outputFormat === "json" || parsed.outputFormat === "auto" && shouldEmitJson())) {
     printCommandEnvelope(baseEnvelope, { json: true });
     return 0;
   }
@@ -21928,6 +22009,17 @@ async function executeTool(args) {
     return 0;
   }
   if (!listConversion) {
+    if (parsed.outPath) {
+      const error = new Error(
+        `${parsed.toolId} did not expose row-shaped output to write as CSV. Re-run with --json to inspect the raw tool response.`
+      );
+      if (argsWantJson(args)) {
+        printJsonError(error);
+      } else {
+        console.error(error.message);
+      }
+      return 1;
+    }
     if (parsed.outputFormat === "csv" || parsed.outputFormat === "csv_file") {
       const jsonPath = writeJsonOutputFile(
         rawResponse,
@@ -21949,7 +22041,8 @@ async function executeTool(args) {
   }
   const csv = writeCsvOutputFile(
     listConversion.rows,
-    `${parsed.toolId}_output`
+    `${parsed.toolId}_output`,
+    parsed.outPath ? { outPath: parsed.outPath } : void 0
   );
   const seededScript = seedToolListScript({
     toolId: parsed.toolId,
@@ -22022,6 +22115,27 @@ async function executeTool(args) {
     );
     return 0;
   }
+  if (parsed.outPath) {
+    printCommandEnvelope(
+      {
+        ...materializedEnvelope,
+        csv_path: csv.path,
+        row_count: csv.rowCount,
+        row_count_returned: csv.rowCount,
+        columns: csv.columns,
+        preview: csv.preview,
+        list_strategy: listConversion.strategy,
+        list_source_path: listConversion.sourcePath,
+        summary
+      },
+      {
+        json: argsWantJson(args) || shouldEmitJson(),
+        text: `Wrote ${csv.rowCount} row(s) to ${csv.path}
+`
+      }
+    );
+    return 0;
+  }
   if (parsed.noPreview) {
     printCommandEnvelope(
       {
@@ -23563,6 +23677,40 @@ function isCi() {
 function shouldSkipSelfUpdate() {
   return envTruthy("DEEPLINE_SKIP_SELF_UPDATE") || envTruthy("DEEPLINE_NO_AUTO_UPDATE") || envTruthy("DEEPLINE_SKIP_SDK_AUTO_UPDATE") || envTruthy("DEEPLINE_DISABLE_AUTO_UPDATE") || isCi();
 }
+function parseSemver(version) {
+  const trimmed = version?.trim();
+  if (!trimmed) return null;
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(
+    trimmed
+  );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? ""
+  };
+}
+function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) {
+    return left.localeCompare(right);
+  }
+  for (const key of ["major", "minor", "patch"]) {
+    if (a[key] !== b[key]) return a[key] > b[key] ? 1 : -1;
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (!a.prerelease) return 1;
+  if (!b.prerelease) return -1;
+  return a.prerelease.localeCompare(b.prerelease);
+}
+function isDowngradeAutoUpdateResponse(response) {
+  const target = response?.latest?.trim();
+  const current = response?.current?.trim() || SDK_VERSION;
+  if (!target) return false;
+  return compareSemver(target, current) < 0;
+}
 function relaunchCurrentCommand(plan) {
   return new Promise((resolve13) => {
     const command = plan.kind === "python-sidecar" ? plan.sidecarPath : process.execPath;
@@ -23590,6 +23738,15 @@ async function maybeAutoUpdateAndRelaunch(response) {
   if (!response || !autoUpdate?.should_auto_update || shouldSkipSelfUpdate()) {
     return false;
   }
+  if (isDowngradeAutoUpdateResponse(response)) {
+    const target = response.latest;
+    const current = response.current?.trim() || SDK_VERSION;
+    process.stderr.write(
+      `Deepline SDK/CLI auto-update refused: server advertised older ${target} than current ${current}. Continuing without mutating the CLI.
+`
+    );
+    return false;
+  }
   const packageSpec = response.latest ? `deepline@${response.latest}` : void 0;
   const plan = resolveUpdatePlan({ packageSpec });
   if (plan.kind === "source") {