deepline 0.3.280 → 0.3.282

package/dist/cli/index.mjs

@@ -3510,7 +3510,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.280",
+  version: "0.3.282",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -4165,7 +4165,7 @@ function applyExplicitHeaders(headers, explicit) {
     for (const existing of Object.keys(headers)) {
       if (existing.toLowerCase() === name) delete headers[existing];
     }
-    headers[name] = value;
+    headers[rawName.trim()] = value;
   }
   return headers;
 }
@@ -4253,7 +4253,7 @@ var HttpClient = class {
     }
   }
   authHeaders(extra) {
-    const headers = {
+    const transportHeaders = {
       Authorization: `Bearer ${this.config.apiKey}`,
       "User-Agent": `deepline-ts-sdk/${SDK_VERSION}`,
       "X-Deepline-Client-Family": "sdk",
@@ -4262,10 +4262,9 @@ var HttpClient = class {
       "X-Deepline-CLI-Version": SDK_VERSION,
       "X-Deepline-SDK-Version": SDK_VERSION,
       "X-Deepline-API-Contract": SDK_API_CONTRACT,
-      "X-Deepline-Run-Result-Shape": "canonical",
-      ...extra,
-      ...deploymentProtectionHeaders()
+      "X-Deepline-Run-Result-Shape": "canonical"
     };
+    const headers = deploymentProtectionHeaders();
     const skillsVersion = this.readSkillsVersionHeader();
     if (skillsVersion) {
       headers["X-Deepline-Skills-Version"] = skillsVersion;
@@ -4311,7 +4310,13 @@ var HttpClient = class {
     if (coordinatorInternalToken?.trim() && (coordinatorUrl?.trim() || workerCallbackUrl?.trim() || runtimeTestFault?.trim() || absurdReleaseOverride?.trim() || preferredReceiptGatewayMachineId?.trim())) {
       headers[COORDINATOR_INTERNAL_TOKEN_HEADER] = coordinatorInternalToken.trim();
     }
-    return applyExplicitHeaders(headers, this.config.headers);
+    return applyExplicitHeaders(
+      applyExplicitHeaders(
+        applyExplicitHeaders(transportHeaders, extra),
+        headers
+      ),
+      this.config.headers
+    );
   }
   /**
    * Send an HTTP request with automatic retries and error handling.
@@ -4335,7 +4340,7 @@ var HttpClient = class {
     let networkPhase = "before_request";
     const headers = this.authHeaders(options?.headers);
     if (options?.body !== void 0) {
-      headers["Content-Type"] = "application/json";
+      applyExplicitHeaders(headers, { "Content-Type": "application/json" });
     }
     let lastError = null;
     const candidateUrls = options?.exactUrlOnly ? [url] : buildCandidateUrls(url);
@@ -4594,7 +4599,7 @@ var HttpClient = class {
       ...options?.headers
     });
     if (options?.body !== void 0) {
-      headers["Content-Type"] = "application/json";
+      applyExplicitHeaders(headers, { "Content-Type": "application/json" });
     }
     let lastError = null;
     for (const candidateUrl of buildCandidateUrls(url)) {
@@ -5636,6 +5641,182 @@ var RUN_EVENT_SEARCH_FALLBACK_KIND_SQL_LITERAL = sqlStringLiteral(
   RUN_EVENT_SEARCH_FALLBACK_KIND
 );
 
+// ../play-data-plane/runtime-sheet-orm.ts
+var RUNTIME_SHEET_CELL_META_COLUMN = {
+  name: "_cell_meta",
+  dataType: "jsonb",
+  nullable: "NO",
+  defaultSql: "'{}'::jsonb"
+};
+var RUNTIME_SHEET_COLUMN_CONTRACTS = [
+  {
+    name: "_key",
+    sqlType: "text",
+    dataType: "text",
+    nullable: "NO",
+    defaultSql: null,
+    repairable: false,
+    requiresDefault: false
+  },
+  {
+    name: "_status",
+    sqlType: "text NOT NULL",
+    dataType: "text",
+    nullable: "NO",
+    defaultSql: null,
+    repairable: false,
+    requiresDefault: false
+  },
+  {
+    name: "_run_id",
+    sqlType: "text",
+    dataType: "text",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_error",
+    sqlType: "text",
+    dataType: "text",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_stage",
+    sqlType: "text",
+    dataType: "text",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_provider",
+    sqlType: "text",
+    dataType: "text",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_input_index",
+    sqlType: "bigint",
+    dataType: "bigint",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_attempt_id",
+    sqlType: "text",
+    dataType: "text",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_attempt_owner_run_id",
+    sqlType: "text",
+    dataType: "text",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_attempt_expires_at",
+    sqlType: "timestamptz",
+    dataType: "timestamp with time zone",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_attempt_seq",
+    sqlType: "integer",
+    dataType: "integer",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_write_version",
+    sqlType: "bigint NOT NULL DEFAULT 0",
+    dataType: "bigint",
+    nullable: "NO",
+    defaultSql: "0",
+    repairable: true,
+    requiresDefault: true
+  },
+  {
+    name: "_writer_run_id",
+    sqlType: "text",
+    dataType: "text",
+    nullable: "YES",
+    defaultSql: null,
+    repairable: true,
+    requiresDefault: false
+  },
+  {
+    name: "_created_at",
+    sqlType: "timestamptz NOT NULL DEFAULT now()",
+    dataType: "timestamp with time zone",
+    nullable: "NO",
+    defaultSql: "now()",
+    repairable: true,
+    requiresDefault: true
+  },
+  {
+    name: "_updated_at",
+    sqlType: "timestamptz NOT NULL DEFAULT now()",
+    dataType: "timestamp with time zone",
+    nullable: "NO",
+    defaultSql: "now()",
+    repairable: true,
+    requiresDefault: true
+  },
+  {
+    name: "_version",
+    sqlType: "bigint NOT NULL",
+    dataType: "bigint",
+    nullable: "NO",
+    defaultSql: null,
+    defaultKind: "version_sequence",
+    repairable: true,
+    requiresDefault: true
+  },
+  {
+    ...RUNTIME_SHEET_CELL_META_COLUMN,
+    sqlType: `jsonb NOT NULL DEFAULT ${RUNTIME_SHEET_CELL_META_COLUMN.defaultSql}`,
+    repairable: true,
+    requiresDefault: true
+  }
+];
+var RUNTIME_SHEET_ATTEMPT_COLUMNS = RUNTIME_SHEET_COLUMN_CONTRACTS.filter(
+  (column) => column.name.startsWith("_attempt_")
+).map((column) => column.name);
+var RUNTIME_SHEET_WRITE_VERSION_COLUMNS = RUNTIME_SHEET_COLUMN_CONTRACTS.filter(
+  (column) => column.name === "_write_version" || column.name === "_writer_run_id"
+).map((column) => column.name);
+var RUNTIME_SHEET_TIMESTAMP_COLUMNS = RUNTIME_SHEET_COLUMN_CONTRACTS.filter(
+  (column) => column.name === "_created_at" || column.name === "_updated_at"
+).map((column) => column.name);
+var RUNTIME_SHEET_SYSTEM_COLUMNS = new Set(
+  RUNTIME_SHEET_COLUMN_CONTRACTS.map((column) => column.name)
+);
+var RUNTIME_SHEET_REPAIRABLE_COLUMNS = RUNTIME_SHEET_COLUMN_CONTRACTS.filter(
+  (column) => column.repairable
+);
+
 // ../play-runtime/run-ledger.ts
 var TERMINAL_STATUS_BY_EVENT_TYPE = {
   [RUN_EVENT_KIND.runCompleted]: "completed",
@@ -7579,7 +7760,7 @@ var DeeplineClient = class _DeeplineClient {
   /**
    * Execute a tool and return the standard execution envelope.
    *
-   * The `toolResponse.raw` field contains the raw tool response.
+   * The `toolResponse.rawV2` field contains the complete parsed and scrubbed tool response.
    * `toolResponse.meta` contains tool/provider metadata.
    * Top-level fields such as `status`, `job_id`, and `billing` describe the
    * Deepline execution envelope.
@@ -12548,15 +12729,42 @@ async function handleBalance(options) {
   const lines = [`Balance: ${payload.balance ?? "(unknown)"} credits`];
   const temporaryHolds = payload.temporary_hold_credits;
   if (typeof temporaryHolds === "number" && temporaryHolds > 0) {
-    lines.push(
-      `Temporarily reserved: ${temporaryHolds} credits \u2014 not charged; unused credits are released after final usage is calculated.`
-    );
+    lines.push(`Open reservation exposure: ${temporaryHolds} credits.`);
   } else if (temporaryHolds === null) {
     lines.push("Temporary reservation status is temporarily unavailable.");
   }
   if (payload.temporary_hold_credits_truncated === true) {
     lines.push("Temporary reservation total may be incomplete.");
   }
+  if (typeof payload.estimated_hold_credits === "number") {
+    lines.push(
+      `Estimated holds: ${payload.estimated_hold_credits} credits \u2014 final usage is not recorded yet.`
+    );
+  }
+  if (typeof payload.incurred_unsettled_credits === "number") {
+    lines.push(
+      `Incurred, awaiting settlement: ${payload.incurred_unsettled_credits} credits.`
+    );
+  }
+  if (typeof payload.pending_wallet_debit_credits === "number") {
+    lines.push(
+      `Pending wallet debit: ${payload.pending_wallet_debit_credits} credits \u2014 excludes amounts already debited for funded holds.`
+    );
+  }
+  if (typeof payload.pending_wallet_refund_credits === "number" && payload.pending_wallet_refund_credits > 0) {
+    lines.push(
+      `Pending wallet refund: ${payload.pending_wallet_refund_credits} credits.`
+    );
+  }
+  if (payload.exposure_status === "partial") {
+    lines.push(
+      "Exposure amounts are lower bounds: some reservations are unpriced or the scan is incomplete."
+    );
+  } else if (payload.exposure_status !== "complete") {
+    lines.push(
+      "The estimated and incurred usage breakdown is temporarily unavailable."
+    );
+  }
   if (status === "no_billing") {
     lines.push(
       "Billing: No billing account or payment method set up for this workspace."
@@ -25518,7 +25726,7 @@ async function traceCliSpan(phase, fields2, run) {
 }
 
 // src/cli/play-check-hints.ts
-var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific scalar fields, and `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
+var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.rawV2` for provider/tool-specific scalar fields after inspecting the observed response envelope, and `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
 var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy, durable, and async-only. Use `.count()`, `.first()`, `.at(index)`, `.peek(n)`, `.materialize(limit)`, or async iteration; do not use `.length`, numeric indexing, spread, synchronous iteration, `.rows`, or `.toArray()`.";
 var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
 var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and result-cache identity; terminal cache reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
@@ -32009,6 +32217,7 @@ async function fetchBackingDatasetRows(input2) {
     return null;
   }
   const sheetRows = [];
+  const seenEnvelopeKeys = /* @__PURE__ */ new Set();
   let offset = 0;
   let settledTotal = null;
   while (true) {
@@ -32020,6 +32229,27 @@ async function fetchBackingDatasetRows(input2) {
       offset,
       rowMode: "all"
     });
+    for (const row of page.rows) {
+      const key = readRecord(getRecordField(row, "data")) ? getStringField(row, "key") : null;
+      if (key === null) continue;
+      if (seenEnvelopeKeys.has(key)) {
+        const activeRun = !TERMINAL_PLAY_STATUSES.has(input2.status.status);
+        const waitCommand = `${input2.retryCommand} --wait`;
+        throw new DeeplineError(
+          "The backing dataset returned a Runtime Sheet row more than once while paging; the export is not ready to write. " + (activeRun ? `Wait for this same run: ${waitCommand}. Do not rerun the Play to retrieve results.` : `Retry with: ${input2.retryCommand}`),
+          void 0,
+          "RUN_EXPORT_NOT_READY",
+          {
+            runId: input2.status.runId,
+            reason: "unstable_pagination",
+            tableNamespace,
+            retry_command: input2.retryCommand,
+            ...activeRun ? { wait_command: waitCommand, do_not_rerun: true } : {}
+          }
+        );
+      }
+      seenEnvelopeKeys.add(key);
+    }
     sheetRows.push(...page.rows);
     const summaryTotal = page.summary?.stats?.total;
     if (typeof summaryTotal === "number" && Number.isFinite(summaryTotal)) {
@@ -32035,15 +32265,23 @@ async function fetchBackingDatasetRows(input2) {
       (row) => Boolean(row) && typeof row === "object" && !Array.isArray(row)
     )
   );
-  const rows = sheetRows.map((row) => {
-    const data = exportableSheetRow(row);
-    return data && withError ? {
-      ...data,
-      [TABLE_EXPORT_ERROR_COLUMN]: tableExportErrorCell(
-        row
-      )
-    } : data;
-  }).filter((row) => Boolean(row));
+  const exportedRowOutcomes = { succeeded: 0, failed: 0, unconfirmed: 0 };
+  const rows = sheetRows.flatMap((row) => {
+    const exported = exportableSheetRow(row);
+    if (!exported) return [];
+    const status = readRecord(getRecordField(row, "data")) ? getStringField(row, "status") : null;
+    if (status === "completed") exportedRowOutcomes.succeeded += 1;
+    else if (status === "failed") exportedRowOutcomes.failed += 1;
+    else exportedRowOutcomes.unconfirmed += 1;
+    return [
+      withError ? {
+        ...exported,
+        [TABLE_EXPORT_ERROR_COLUMN]: tableExportErrorCell(
+          row
+        )
+      } : exported
+    ];
+  });
   const hasCompleteSettledPrefix = acceptsSettledRowsAsCompleteExport(input2.status) && settledTotal !== null && // A zero-row run-scoped read is not a settled export when the returned
   // Dataset Handle advertised rows. That shape is the replay/reuse case:
   // the rows belong to another writer (or the projection has not caught up)
@@ -32058,7 +32296,8 @@ async function fetchBackingDatasetRows(input2) {
       source: `${input2.rowsInfo.source ?? "result.rows"} -> /api/v2/plays/${playName}/sheet?tableNamespace=${tableNamespace}`
     };
   }
-  if (rows.length < input2.rowsInfo.totalRows && !hasCompleteSettledPrefix) {
+  const hasActiveSnapshot = !TERMINAL_PLAY_STATUSES.has(input2.status.status) && rows.length > 0 && exportedRowOutcomes.unconfirmed === 0;
+  if (rows.length < input2.rowsInfo.totalRows && !hasCompleteSettledPrefix && !hasActiveSnapshot) {
     return null;
   }
   const columns = mergeExportColumns(
@@ -32070,7 +32309,10 @@ async function fetchBackingDatasetRows(input2) {
     rows,
     columns,
     totalRows: rows.length,
+    // All pages of the selected snapshot were fetched. The CLI receipt
+    // independently marks an active run's export as partial.
     complete: true,
+    exportedRowOutcomes,
     currentTable: void 0,
     source: `${input2.rowsInfo.source ?? "result.rows"} -> /api/v2/plays/${playName}/sheet?tableNamespace=${tableNamespace}`
   };
@@ -32111,10 +32353,30 @@ function assertDatasetHasExportableRows(input2) {
   const inspectCommand = `deepline runs get ${input2.status.runId} --full --json`;
   const retryCommand = runExportRetryCommand(
     input2.status.runId,
-    "output.csv",
-    datasetLabel
+    input2.outPath ?? "output.csv",
+    datasetLabel,
+    input2.format ? { format: input2.format } : void 0
   );
   const currentTableQueryCommand2 = input2.rowsInfo.currentTableQueryCommand;
+  if (!TERMINAL_PLAY_STATUSES.has(input2.status.status)) {
+    const waitCommand = `${retryCommand} --wait`;
+    throw new DeeplineError(
+      `Run ${input2.status.runId} is ${runStatus}; this dataset has no accepted rows to export yet. Wait for this same run: ${waitCommand}. Do not start another run to retrieve results.`,
+      void 0,
+      "RUN_EXPORT_EMPTY",
+      {
+        runId: input2.status.runId,
+        dataset: datasetLabel,
+        runStatus,
+        guidance: {
+          wait_command: waitCommand,
+          inspect_command: inspectCommand,
+          do_not_rerun: true,
+          reason: "The run is still active and has no accepted rows in this dataset."
+        }
+      }
+    );
+  }
   const explanation = terminalRunWithMissingAdvertisedRows ? ` The terminal result advertised ${advertisedRows} row(s), but none are currently attributed to this run's durable sheet. Those rows may have been reused from an earlier run or the projection may still be lagging; export refuses to guess another run's rows. Retry the same export after projection catches up (do not rerun the Play): ${retryCommand}. If it remains empty, inspect the full package with ${inspectCommand}` + (currentTableQueryCommand2 ? `, then inspect the current table's _run_id/_writer_run_id with ${currentTableQueryCommand2} and export the run that owns those rows` : " and export the run that owns the durable dataset") + "; this command will not use a database-wide table query that could mix runs." : ` The run status is '${runStatus || "unknown"}', so it likely failed before persisting rows to this dataset. That means provider calls may have been billed without a durable row; inspect ${inspectCommand}, fix the failure cause, then rerun the Play so completed receipts can be reused.`;
   throw new DeeplineError(
     `Run ${input2.status.runId} has zero rows to export from dataset '${datasetLabel}'.` + explanation + (available.length > 0 ? ` Available datasets: ${available.join(", ")}.` : " No datasets were materialized for this run."),
@@ -32251,16 +32513,23 @@ ${commands.join("\n")}`,
   }
   const attempts = Math.max(1, Math.trunc(options.attempts ?? 1));
   const retryDelayMs = Math.max(0, Math.trunc(options.retryDelayMs ?? 0));
+  const retryCommand = runExportRetryCommand(
+    status.runId,
+    outPath,
+    options.datasetPath ?? rowsInfo.source,
+    options
+  );
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
     let fetchedRowsInfo = null;
     try {
       fetchedRowsInfo = await fetchBackingDatasetRows({
         client: client2,
         status,
-        rowsInfo
+        rowsInfo,
+        retryCommand
       });
     } catch (error) {
-      if (error instanceof DeeplineError && error.code === "RUN_EXPORT_SCOPE_MISMATCH") {
+      if (error instanceof DeeplineError && (error.code === "RUN_EXPORT_SCOPE_MISMATCH" || error.code === "RUN_EXPORT_NOT_READY")) {
         throw error;
       }
       if (!canExportPreview) {
@@ -32272,7 +32541,9 @@ ${commands.join("\n")}`,
         rowsInfo: fetchedRowsInfo,
         status,
         availableRows,
-        datasetPath: options.datasetPath
+        datasetPath: options.datasetPath,
+        outPath,
+        format: options.format
       });
       return writeExport(guarded2);
     }
@@ -32281,7 +32552,9 @@ ${commands.join("\n")}`,
         rowsInfo,
         status,
         availableRows,
-        datasetPath: options.datasetPath
+        datasetPath: options.datasetPath,
+        outPath,
+        format: options.format
       });
       return writeExport(guarded2);
     }
@@ -32290,15 +32563,11 @@ ${commands.join("\n")}`,
     }
   }
   if (!canExportPreview) {
-    const retryCommand = runExportRetryCommand(
-      status.runId,
-      outPath,
-      options.datasetPath ?? rowsInfo.source,
-      options
-    );
     const previewReason = rowsInfo.currentTable ? "Legacy shared-table metadata does not prove this preview belongs to the run" : `Run output only includes ${rowsInfo.rows.length} preview row(s) of ${rowsInfo.totalRows}`;
+    const activeRun = !TERMINAL_PLAY_STATUSES.has(status.status);
+    const waitCommand = `${retryCommand} --wait`;
     throw new DeeplineError(
-      `${previewReason}; the backing dataset was not ready to export yet. Retry with: ${retryCommand}`,
+      `${previewReason}; the backing dataset was not ready to export yet. ` + (activeRun ? `The run is ${status.status}. Wait for this same run: ${waitCommand}. Do not rerun the Play to retrieve results.` : `Retry with: ${retryCommand}`),
       void 0,
       "RUN_EXPORT_NOT_READY",
       {
@@ -32307,7 +32576,8 @@ ${commands.join("\n")}`,
         totalRows: rowsInfo.totalRows,
         tableNamespace: rowsInfo.tableNamespace ?? null,
         dataset: options.datasetPath ?? rowsInfo.source,
-        retry_command: retryCommand
+        retry_command: retryCommand,
+        ...activeRun ? { wait_command: waitCommand, do_not_rerun: true } : {}
       }
     );
   }
@@ -32315,7 +32585,9 @@ ${commands.join("\n")}`,
     rowsInfo,
     status,
     availableRows,
-    datasetPath: options.datasetPath
+    datasetPath: options.datasetPath,
+    outPath,
+    format: options.format
   });
   return writeExport(guarded);
 }
@@ -33075,7 +33347,7 @@ function checkHintExpression(value) {
   return stringValue3(value).replace(/^toolExecutionResult\./, "result.");
 }
 function checkHintRawPath(value) {
-  return value?.replace(/^toolResponse\./, "result.toolResponse.");
+  return value?.startsWith("toolResponse.rawV2") ? value.replace(/^toolResponse\./, "result.toolResponse.") : void 0;
 }
 function collectStaticPipelineToolIds(staticPipeline) {
   const seen = /* @__PURE__ */ new Set();
@@ -33120,7 +33392,7 @@ function toolGetterHintFromMetadata(toolId, tool) {
     toolId,
     lists,
     values,
-    raw: checkHintExpression(toolResponse.raw) || "result.toolResponse.raw"
+    raw: checkHintExpression(toolResponse.rawV2) || "result.toolResponse.rawV2"
   };
 }
 async function buildToolGetterHints(client2, staticPipeline) {
@@ -33135,7 +33407,7 @@ async function buildToolGetterHints(client2, staticPipeline) {
           toolId,
           lists: [],
           values: [],
-          raw: "result.toolResponse.raw",
+          raw: "result.toolResponse.rawV2",
           unavailable: error instanceof Error ? error.message : String(error)
         };
       }
@@ -35123,7 +35395,7 @@ async function handleRunStopAll(args) {
 async function handleRunExport(args) {
   const selection = parseJsonFields(args, "export");
   args = selection.args;
-  const usage2 = "Usage: deepline runs export <run-id> [--dataset result.rows] --out <path> [--format csv|json] [--metadata-out export.json] [--json]";
+  const usage2 = "Usage: deepline runs export <run-id> [--dataset result.rows] --out <path> [--format csv|json] [--wait] [--timeout-ms 300000] [--metadata-out export.json] [--json]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage2);
@@ -35135,6 +35407,8 @@ async function handleRunExport(args) {
   let datasetPath = null;
   let metadataOutPath = null;
   let format = "csv";
+  const wait = args.includes("--wait");
+  let waitTimeoutMs = 3e5;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--out" && args[index + 1]) {
@@ -35149,6 +35423,16 @@ async function handleRunExport(args) {
       metadataOutPath = resolve13(args[++index]);
     }
     if (arg === "--format") format = args[++index] ?? "";
+    if (arg === "--timeout-ms") {
+      waitTimeoutMs = parsePositiveInteger3(args[++index] ?? "", arg);
+      if (!wait) {
+        throw new DeeplineError(
+          "--timeout-ms requires --wait.",
+          void 0,
+          "INVALID_ARGUMENT"
+        );
+      }
+    }
   }
   if (!outPath) {
     console.error(usage2);
@@ -35169,7 +35453,33 @@ async function handleRunExport(args) {
     );
   }
   const client2 = new DeeplineClient();
-  const status = await client2.getPlayStatus(runId, { full: true });
+  let status = await client2.getPlayStatus(runId, { full: true });
+  if (wait && !TERMINAL_PLAY_STATUSES.has(status.status)) {
+    const progress = createCliProgress(!argsWantJson(args));
+    try {
+      await waitForPlayCompletionByWatch({
+        client: client2,
+        playName: extractRunPlayName(status) ?? runId,
+        workflowId: runId,
+        jsonOutput: argsWantJson(args),
+        emitLogs: false,
+        waitTimeoutMs,
+        startedAt: Date.now(),
+        state: {
+          emittedRunnerStarted: false,
+          lastProgressSignature: null,
+          lastProgressHeartbeatAt: 0,
+          lastStatusHeartbeatAt: 0
+        },
+        progress
+      });
+      status = await client2.getPlayStatus(runId, { full: true });
+      progress.complete();
+    } catch (error) {
+      progress.fail();
+      throw error;
+    }
+  }
   const exportResult = await exportPlayStatusRows(client2, status, outPath, {
     datasetPath,
     format
@@ -35193,8 +35503,16 @@ async function handleRunExport(args) {
     { format }
   );
   const fileLocation = format === "json" ? { json_path: exportResult?.path ?? null } : { csv_path: exportResult?.path ?? null };
+  const exportedRowOutcomes = exportResult?.rowsInfo.exportedRowOutcomes;
+  const rowFailures = exportedRowOutcomes && exportedRowOutcomes.failed > 0 ? {
+    count: exportedRowOutcomes.failed,
+    message: "Failed rows can retain values from stages that completed earlier; those values do not prove the row succeeded.",
+    inspectCommand: `deepline runs get ${status.runId} --json`
+  } : null;
   const payload = {
     runId: status.runId,
+    runStatus: status.status,
+    isPartial: !TERMINAL_PLAY_STATUSES.has(status.status),
     datasets: identity ? [identity] : resolved ? [
       {
         ...resolved.datasetId ? { datasetId: resolved.datasetId } : {},
@@ -35206,18 +35524,30 @@ async function handleRunExport(args) {
     format,
     source,
     rowCount: exportResult?.rowsInfo.totalRows ?? null,
+    ...exportedRowOutcomes ? { rowOutcomes: exportedRowOutcomes } : {},
+    ...rowFailures ? { rowFailures } : {},
     columns: underscoreKeysLast(exportResult?.rowsInfo.columns ?? []),
     ...currentTableNotice ? { notice: currentTableNotice } : {},
-    ...metadataOutPath ? { metadata_path: metadataOutPath } : {}
+    ...metadataOutPath ? { metadata_path: metadataOutPath } : {},
+    ...!TERMINAL_PLAY_STATUSES.has(status.status) ? { completionCommand: `${exportCommand} --wait` } : {}
   };
   const lines = withRunNavigationLines(
     [
       `Exported ${status.runId} to ${exportResult?.path ?? outPath}`,
+      ...!TERMINAL_PLAY_STATUSES.has(status.status) ? [
+        `Partial export: run is ${status.status}; more rows may be saved.`,
+        `Export after completion: ${exportCommand} --wait`
+      ] : status.status === "failed" || status.status === "cancelled" ? [
+        `Saved rows from a ${status.status} run. Inspect: deepline runs get ${status.runId} --json`
+      ] : [],
       ...currentTableNotice ? [
         "Current shared dataset: this export may include writes from another run.",
         `This run's full returned output: ${currentTableNotice.full_run_output_command}`
       ] : [],
-      ...source ? [`source=${source}`] : []
+      ...source ? [`source=${source}`] : [],
+      ...rowFailures ? [
+        `${rowFailures.count} failed row(s) included. Earlier saved values do not prove success. Inspect: ${rowFailures.inspectCommand}`
+      ] : []
     ],
     status,
     payload.actions
@@ -37365,6 +37695,10 @@ Notes:
   --json controls stdout metadata, not the file format.
   --metadata-out writes the same export metadata object returned by --json,
   including the source dataset path and row/column metadata.
+  An active run exports only the rows accepted so far; the receipt labels it
+  partial. --wait observes the same run until it completes, fails, or is cancelled
+  before exporting its saved rows. --timeout-ms bounds that wait (default 300000);
+  a wait timeout leaves the run and destination file untouched.
 
 Examples:
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
@@ -37372,11 +37706,15 @@ Examples:
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv --metadata-out output.meta.json
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv --json
   deepline runs export play/my-play/run/20260501t000000-000 --format json --out rows.json
+  deepline runs export play/my-play/run/20260501t000000-000 --out rows.csv --wait --timeout-ms 600000
 `
   ).requiredOption("--out <path>", "Output file path").option("--format <format>", "File format: csv or json", "csv").option(
     "--dataset <path>",
     "Returned dataset handle path, such as result.rows"
   ).option("--metadata-out <path>", "Write export metadata JSON to a file").option(
+    "--wait",
+    "Wait for this run to reach a terminal status before export"
+  ).option("--timeout-ms <ms>", "Maximum wait with --wait (default: 300000)").option(
     "--json [fields]",
     "JSON receipt; optionally select fields (dataset,datasets,actions). Does not filter exported rows"
   ).action(async (runId, options) => {
@@ -37388,6 +37726,8 @@ Examples:
       "--format",
       options.format,
       ...options.metadataOut ? ["--metadata-out", options.metadataOut] : [],
+      ...options.wait ? ["--wait"] : [],
+      ...options.timeoutMs ? ["--timeout-ms", options.timeoutMs] : [],
       ...jsonFieldArgs(options.json)
     ]);
   });
@@ -56206,6 +56546,9 @@ function printCompactToolContract(tool, requestedToolId) {
     }
   }
   console.log("");
+  console.log(
+    "Provider-specific fields: inspect result.toolResponse.rawV2 and its observed envelope. Prefer the declared getters above."
+  );
   console.log(
     `More: deepline tools describe ${contract.toolId} --pricing-only | --schema-only | --examples-only | --getters-only | --json`
   );
@@ -56461,7 +56804,7 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
     runtimeOutputHelp: {
       contract: "tools describe shows declared schema and Deepline getters; it is not an observed provider response.",
       getterScope: "extractedValues/extractedLists .get() only works for declared Deepline getters listed in usageGuidance.toolExecutionResult.",
-      rawToolResponse: "Use toolExecutionResult.toolResponse.raw for provider/tool-specific scalar fields, fields in outputSchema that are not declared getters, and debugging. For declared row/list outputs, use extractedLists.<name>.get(); raw row arrays may be inline previews.",
+      rawToolResponse: "Use toolExecutionResult.toolResponse.rawV2 for provider/tool-specific scalar fields, fields in outputSchema that are not declared getters, and debugging. Inspect the observed response envelope before selecting nested fields. For declared row/list outputs, use extractedLists.<name>.get().",
       invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter.",
       observeActualShape: observedOutputCommand,
       observedOutput: observedOutputCommand,
@@ -56483,14 +56826,18 @@ function usageGuidanceWithAccessDefaults(usageGuidance) {
       },
       extractedValues: {
         expression: "toolExecutionResult.extractedValues.<name>.get()",
-        meaning: "Declared Deepline scalar extractors only."
+        meaning: "Declared Deepline scalar or normalized object extractors only."
       },
+      ...existingAccess,
       rawToolResponse: {
-        expression: "toolExecutionResult.toolResponse.raw",
-        meaning: "Raw tool response for provider/tool-specific scalar fields and bounded debugging. Declared row/list outputs should use extractedLists.<name>.get(); raw row arrays may be inline previews."
+        expression: "toolExecutionResult.toolResponse.rawV2",
+        meaning: "Complete parsed and scrubbed provider response for provider/tool-specific scalar fields and debugging. Inspect its envelope before selecting nested fields. Declared row/list outputs should use extractedLists.<name>.get()."
+      },
+      canonicalToolResponse: {
+        expression: "toolExecutionResult.toolResponse.rawV2",
+        meaning: "Complete parsed and scrubbed provider response, including envelope siblings, pagination, and metadata."
       },
-      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; use toolResponse.raw for provider/tool-specific scalar fields, and extractedLists.<name>.get() for declared row/list outputs.",
-      ...existingAccess
+      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; inspect toolResponse.rawV2 for provider/tool-specific scalar fields, and use extractedLists.<name>.get() for declared row/list outputs."
     }
   };
 }