deepline 0.3.290 → 0.3.292

package/dist/cli/index.js

@@ -3515,7 +3515,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.290",
+  version: "0.3.292",
   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
@@ -5982,7 +5982,7 @@ function classifyLegacyLogLine(line) {
   if (/^\[perf\] runtime receipt\b/i.test(message)) {
     return "receipt";
   }
-  if (/^\[perf\] runtime (?:map|state)\b/i.test(message) || /\[worker\] picked up run\b/.test(message) || /\[worker\] heartbeat\b/.test(message) || /\[worker\] progress completedRows=\d+ totalRows=\d+ rowUpdates=\d+/.test(
+  if (/^\[perf\]/i.test(message) || /^\[runtime\.(?:phase_summary|logs|log_transport)\]/i.test(message) || /\[worker\] picked up run\b/.test(message) || /\[worker\] heartbeat\b/.test(message) || /\[worker\] progress completedRows=\d+ totalRows=\d+ rowUpdates=\d+/.test(
     message
   ) || /\[worker\] step started\b/.test(message) || /\[worker\] Preparing run files\b/.test(message) || /\[worker\] Run files ready\b/.test(message) || /\[worker\] Runtime ready\b/.test(message) || /\[worker\] Sandbox (?:starting|create start|create done|workspace ready|upload start|runner uploaded)\b/.test(
     message
@@ -7814,8 +7814,10 @@ var DeeplineClient = class _DeeplineClient {
   /**
    * Execute a tool and return the standard execution envelope.
    *
-   * The `toolResponse.rawV2` field contains the complete parsed and scrubbed tool response.
-   * `toolResponse.meta` contains tool/provider metadata.
+   * The `toolResponse.rawV2` field contains the complete tool response,
+   * preserving its original nesting. Inspect `getTool().examples` for a full
+   * Deepline response example. Optional `toolResponse.responseMeta` contains
+   * response metadata.
    * Top-level fields such as `status`, `job_id`, and `billing` describe the
    * Deepline execution envelope.
    */
@@ -8528,7 +8530,7 @@ var DeeplineClient = class _DeeplineClient {
       });
     } catch (error) {
       failedLogsLoaded = false;
-      const retryCommand = `deepline runs get ${runId} --log-failed --json`;
+      const retryCommand = `deepline runs logs ${runId} --failed --json`;
       const reason = error instanceof Error && error.message.trim() ? ` (${error.message.trim().slice(0, 500)})` : "";
       failedLogs = {
         runId,
@@ -11518,6 +11520,9 @@ function errorToJsonPayload(error) {
   if (maybeRecord?.details && typeof maybeRecord.details === "object" && !Array.isArray(maybeRecord.details)) {
     details.details = maybeRecord.details;
   }
+  if (maybeRecord?.guidance && typeof maybeRecord.guidance === "object" && !Array.isArray(maybeRecord.guidance)) {
+    details.guidance = maybeRecord.guidance;
+  }
   const providerConcurrency = providerConcurrencyDiagnostic(maybeRecord);
   if (providerConcurrency) {
     details.providerConcurrency = providerConcurrency;
@@ -15086,7 +15091,9 @@ async function handleDbQuery(args) {
         actions: [{ label: "Tool equivalent", command: toolCommand }]
       }
     },
-    { json: jsonOutput || format === "json" }
+    {
+      json: explicitJsonOutput || format === "json" || format !== "table" && jsonOutput
+    }
   );
   return 0;
 }
@@ -15162,8 +15169,9 @@ Examples:
     "after",
     `
   Notes:
-  Requires --sql (inline SQL or @file.sql). Output is a compact table in a terminal and raw JSON with
-  --json or when stdout is piped. The active auth workspace determines scope.
+  Requires --sql (inline SQL or @file.sql). Output defaults to a compact table in a terminal
+  and JSON when stdout is piped. --format table forces a table even in pipes.
+  --json overrides --format for stdout. The active auth workspace determines scope.
   Read permitted schemas with SELECT, EXPLAIN, or read-only WITH.
   Write only to schema-qualified storage tables. For example, use
   CREATE TABLE storage.blocked (...) instead of CREATE TABLE blocked (...).
@@ -21734,7 +21742,7 @@ var KIND_DESCRIPTIONS = {
   "dataset.lifecycle": "Dataset registered, available or failed.",
   "activity.observed": "Provider or workflow activity.",
   "work.counters": "Call, request and rate-limit totals.",
-  "receipt.completed": "Saved work result: succeeded.",
+  "receipt.completed": "Saved result or call details.",
   "receipt.failed": "Saved work result: failed.",
   "receipt.skipped": "Saved work result: skipped.",
   "runtime.event": "Other event."
@@ -21775,6 +21783,10 @@ var FILTER_EXAMPLES = [
   {
     label: "One run and step",
     command: `deepline runs logs '<run-id>' --where '$.stepId == "company-lookup"' --json`
+  },
+  {
+    label: "Error logs for one step",
+    command: `deepline runs logs --kind log.appended --where '$.level == "error" && $.stepId == "company-lookup"' --payloads --json`
   }
 ];
 function wrapParagraph(text) {
@@ -21795,10 +21807,14 @@ function renderRunLogsHelp() {
     "",
     "Examples:",
     `  ${READ_EXAMPLES[0]}`,
+    `  deepline runs logs --where '$.eventId == "receipt:5a32ee1a-46cf-4853-b72b-5f1d782ffab4"' --payloads --json`,
     "  deepline runs logs --kind run.failed --json",
-    ...[FILTER_EXAMPLES[1], FILTER_EXAMPLES[2], FILTER_EXAMPLES[5]].map(
-      ({ command }) => `  ${command}`
-    ),
+    ...[
+      FILTER_EXAMPLES[1],
+      FILTER_EXAMPLES[2],
+      FILTER_EXAMPLES[5],
+      FILTER_EXAMPLES[7]
+    ].map(({ command }) => `  ${command}`),
     "",
     "Event kinds:",
     ...RUN_LOGS_KIND_HELP.map(
@@ -21817,6 +21833,7 @@ function renderRunLogsHelp() {
       "A run ID alone reads text logs. Omit it or add a search flag to search events; a supplied run ID narrows the search.",
       "Defaults to the last hour; maximum lookback is seven days. Follow next.logs for events; use nextCursor with --cursor for older text logs.",
       "--payloads returns available details or saved results: up to 10 events and 16 MiB.",
+      "To read one exact saved result, filter by its returned eventId and add --payloads.",
       "--out, --failed and --log-level apply to text logs and cannot be combined with event search."
     ].map((note) => wrapParagraph(note)),
     "",
@@ -22149,13 +22166,6 @@ var DATASET_EXECUTION_BUCKETS = [
   "skipped:missed",
   "failed"
 ];
-function formatDatasetRowCountsLine(counts) {
-  const { persisted, succeeded, failed } = counts;
-  if (succeeded === persisted && failed === 0) {
-    return `${persisted} persisted`;
-  }
-  return `${persisted} persisted (${succeeded} succeeded, ${failed} failed)`;
-}
 
 // src/runs/overview.ts
 var record3 = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
@@ -22174,7 +22184,7 @@ function lifecycleActions(status, id, state) {
   return {
     ...["started", "queued", "running", "waiting"].includes(state ?? "") ? { stopRunCmd: `deepline runs stop ${id} --json` } : {},
     ...state === "failed" ? {
-      getFailedLogsCmd: `deepline runs get ${id} --log-failed --json`,
+      getFailedLogsCmd: `deepline runs logs ${id} --failed --json`,
       ...status.rerunCommand ? { rerunCmd: status.rerunCommand } : {}
     } : {}
   };
@@ -22377,7 +22387,7 @@ function buildRunOverview(status, fullStatus) {
       );
     return {
       datasetId: dataset.datasetId,
-      name: dataset.tableNamespace,
+      name: dataset.tableNamespace ?? (typeof stepOutput?.tableNamespace === "string" ? stepOutput.tableNamespace : dataset.path),
       stepId: step?.id ?? named[0]?.[1].stepId,
       rowCount: dataset.rowCount ?? null,
       ...dataset.lifecycle ? { lifecycle: dataset.lifecycle } : {},
@@ -22471,7 +22481,7 @@ function buildRunOverview(status, fullStatus) {
 function receiptAction(id) {
   const quotedId = `'${id.replace(/'/g, "'\\''")}'`;
   return {
-    getReceiptCmd: `deepline runs receipt ${quotedId} --key '<receipt-key>' --json`
+    getReceiptCmd: `deepline runs logs ${quotedId} --kind receipt.completed --payloads --json`
   };
 }
 function buildRunNavigation(status) {
@@ -24330,7 +24340,7 @@ Examples:
 // src/cli/commands/run-receipt.ts
 var import_promises4 = require("fs/promises");
 function registerRunReceiptCommand(runs) {
-  runs.command("receipt <runId>").description(
+  runs.command("receipt <runId>", { hidden: true }).description(
     "Read retained tool responses by receipt key. Never executes tools."
   ).option(
     "--key <key>",
@@ -24344,8 +24354,7 @@ function registerRunReceiptCommand(runs) {
     "after",
     `
 Examples:
-  deepline runs receipt <run-id> --key '<key-1>' --key '<key-2>'
-  jq -r '.[].receipt_key' rows.json | deepline runs receipt <run-id> --keys - --out responses.json
+  deepline runs logs <run-id> --kind receipt.completed --payloads --json
 
 Returns one outcome per key, preserving order and duplicates. A missing or
 unavailable result is explicit; other keys are still returned. Exit 4 means
@@ -31596,7 +31605,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.rawV2` for provider/tool-specific scalar fields after inspecting the observed response envelope, 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`. Read tool-specific fields from `toolExecutionResult.toolResponse.rawV2` using the nesting shown in the response example, and use `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.";
@@ -36564,12 +36573,13 @@ function buildRunNextCommands(status) {
     };
   }
   const actions2 = buildRunNavigation(status).actions;
+  const exportDatasetCmds = Array.isArray(actions2.exportDatasetCmds) ? actions2.exportDatasetCmds : !status.package && extractCanonicalRowsInfo(status) ? [`deepline runs export ${runId} --out output.csv`] : [];
   const commands = {
     get: String(actions2.getRunCmd ?? `deepline runs get ${runId} --json`),
     full: String(
       actions2.getFullRunCmd ?? `deepline runs get ${runId} --full --json`
     ),
-    ...Array.isArray(actions2.exportDatasetCmds) ? actions2.exportDatasetCmds.length === 1 ? { export: String(actions2.exportDatasetCmds[0]) } : {} : !status.package ? { export: `deepline runs export ${runId} --out output.csv` } : {},
+    ...exportDatasetCmds.length === 1 ? { export: String(exportDatasetCmds[0]) } : {},
     logs: String(
       !status.package ? `deepline runs logs ${runId} --out run.log --json` : actions2.getLogsCmd ?? `deepline runs logs ${runId} --limit 100 --json`
     )
@@ -36578,7 +36588,7 @@ function buildRunNextCommands(status) {
     commands.stop = `deepline runs stop ${runId} --json`;
   }
   if (status.status === "failed") {
-    commands.failedLogs = `deepline runs get ${runId} --log-failed --json`;
+    commands.failedLogs = `deepline runs logs ${runId} --failed --json`;
     if (status.rerunCommand) commands.run = status.rerunCommand;
   }
   if (status.dashboardUrl) {
@@ -37009,7 +37019,7 @@ function compactPlayStatus(status) {
         next: {
           ...readRecord(packaged.next) ?? {},
           ...status.failedLogs ? {
-            failedLogs: `deepline runs get ${status.runId} --log-failed --json`
+            failedLogs: `deepline runs logs ${status.runId} --failed --json`
           } : {},
           ...status.rerunCommand ? { run: status.rerunCommand } : {}
         }
@@ -37022,14 +37032,14 @@ function compactPlayStatus(status) {
       ...status.failedLogs ? {
         next: {
           ...readRecord(packaged.next) ?? {},
-          failedLogs: `deepline runs get ${status.runId} --log-failed --json`
+          failedLogs: `deepline runs logs ${status.runId} --failed --json`
         }
       } : {},
       ...status.rerunCommand ? {
         next: {
           ...readRecord(packaged.next) ?? {},
           ...status.failedLogs ? {
-            failedLogs: `deepline runs get ${status.runId} --log-failed --json`
+            failedLogs: `deepline runs logs ${status.runId} --failed --json`
           } : {},
           run: status.rerunCommand
         }
@@ -37078,9 +37088,6 @@ function compactRunErrorForEnvelope(message, runId) {
   const headline = firstStackFrame >= 0 ? lines.slice(0, firstStackFrame).join("\n") : message;
   return truncateErrorForDisplay(headline, runId, 1e3);
 }
-function readRunPackageRun(packaged) {
-  return packaged.run && typeof packaged.run === "object" && !Array.isArray(packaged.run) ? packaged.run : {};
-}
 function readRecordArray(value) {
   return Array.isArray(value) ? value.filter(
     (item) => item !== null && typeof item === "object" && !Array.isArray(item)
@@ -37092,131 +37099,6 @@ function readRecord(value) {
 function readNonNegativeInteger(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.trunc(value) : null;
 }
-function formatSummaryScalar(value) {
-  if (typeof value === "number") {
-    return Number.isFinite(value) ? formatInteger(Math.trunc(value)) : null;
-  }
-  if (typeof value === "string" || typeof value === "boolean") {
-    return String(value);
-  }
-  if (value === null) {
-    return "null";
-  }
-  return null;
-}
-function formatSummaryScalarParts(record5, skipKeys = /* @__PURE__ */ new Set()) {
-  const parts = [];
-  for (const [key, value] of Object.entries(record5)) {
-    if (skipKeys.has(key)) {
-      continue;
-    }
-    const formatted = formatSummaryScalar(value);
-    if (formatted !== null) {
-      parts.push(`${key}=${formatted}`);
-    }
-  }
-  return parts;
-}
-var DATASET_SUMMARY_TOP_VALUES_DISPLAY_LIMIT = 10;
-function formatTopValuesPart(value) {
-  const topValues = readRecord(value);
-  if (!topValues) {
-    return null;
-  }
-  const entries = Object.entries(topValues).slice(
-    0,
-    DATASET_SUMMARY_TOP_VALUES_DISPLAY_LIMIT
-  );
-  if (entries.length === 0) {
-    return null;
-  }
-  return `top_values=${entries.map(([topValue, count2]) => `${topValue}=${String(count2)}`).join(", ")}`;
-}
-function formatPackageDatasetSummaryLines(summary, indent2 = "    ") {
-  const record5 = readRecord(summary);
-  const columnStats = readRecord(record5?.columnStats);
-  if (!record5 || !columnStats) {
-    return [];
-  }
-  const lines = [];
-  const rowCounts = readRecord(record5.rowCounts);
-  if (rowCounts) {
-    const persisted = readNonNegativeInteger(rowCounts.persisted);
-    const succeeded = readNonNegativeInteger(rowCounts.succeeded);
-    const failed = readNonNegativeInteger(rowCounts.failed);
-    if (persisted !== null) {
-      lines.push(
-        `${indent2}rows: ${formatDatasetRowCountsLine({
-          persisted,
-          succeeded: succeeded ?? persisted,
-          failed: failed ?? 0
-        })}`
-      );
-    }
-  }
-  const parts = formatSummaryScalarParts(
-    record5,
-    /* @__PURE__ */ new Set(["columnStats", "rowCounts"])
-  );
-  if (parts.length > 0) {
-    lines.push(`${indent2}summary: ${parts.join(" ")}`);
-  }
-  for (const [column, rawColumnSummary] of Object.entries(columnStats)) {
-    const columnSummary = readRecord(rawColumnSummary);
-    if (!columnSummary) continue;
-    const execution = readRecord(columnSummary.execution);
-    const executionText = execution ? Object.entries(execution).map(([bucket, value]) => `${bucket}=${String(value)}`).join(", ") : "";
-    const topValuesText = formatTopValuesPart(columnSummary.top_values);
-    const columnParts = [
-      ...formatSummaryScalarParts(
-        columnSummary,
-        /* @__PURE__ */ new Set(["execution", "top_values"])
-      ),
-      topValuesText,
-      executionText ? `execution=${executionText}` : null
-    ].filter(Boolean);
-    if (columnParts.length > 0) {
-      lines.push(`${indent2}  ${column}: ${columnParts.join(" ")}`);
-    }
-  }
-  return lines;
-}
-function actionToCommand(action) {
-  if (!action || typeof action !== "object" || Array.isArray(action)) {
-    return null;
-  }
-  const record5 = action;
-  if (typeof record5.command === "string" && record5.command.trim()) {
-    return record5.command.trim();
-  }
-  if (record5.kind === "deepline_run_inspect" && typeof record5.runId === "string") {
-    return `deepline runs get ${record5.runId} --json`;
-  }
-  if (record5.kind === "deepline_run_full" && typeof record5.runId === "string") {
-    return `deepline runs get ${record5.runId} --full --json`;
-  }
-  if (record5.kind === "deepline_run_billing" && typeof record5.runId === "string") {
-    return `deepline runs get ${record5.runId} --full --json | jq '.billing'`;
-  }
-  if (record5.kind === "deepline_run_export" && typeof record5.runId === "string" && typeof record5.datasetPath === "string") {
-    return `deepline runs export ${record5.runId} --dataset ${shellSingleQuote(
-      record5.datasetPath
-    )} --out ${shellSingleQuote(`${record5.datasetPath.split(".").pop() || "dataset"}.csv`)}`;
-  }
-  if (record5.kind === "deepline_run_logs") {
-    if (typeof record5.command === "string" && record5.command.trim()) {
-      return record5.command;
-    }
-    if (typeof record5.runId === "string") {
-      return record5.view === "failed" ? `deepline runs get ${record5.runId} --log-failed --json` : `deepline runs logs ${record5.runId} --json`;
-    }
-  }
-  if (record5.kind === "deepline_db_query" && typeof record5.sql === "string") {
-    const maxRows = typeof record5.maxRows === "number" && Number.isFinite(record5.maxRows) ? Math.trunc(record5.maxRows) : 20;
-    return `deepline db query --sql ${shellSingleQuote(record5.sql)} --max-rows ${maxRows} --json`;
-  }
-  return null;
-}
 function packageDatasetRecords(packaged) {
   const catalog = readRecordArray(packaged.datasets);
   if (catalog.length > 0) return catalog;
@@ -37225,24 +37107,6 @@ function packageDatasetRecords(packaged) {
     return output2?.kind === "dataset" ? [output2] : [];
   });
 }
-function packageReturnedDatasetIdentity(packaged) {
-  const datasetIds = /* @__PURE__ */ new Set();
-  const paths = /* @__PURE__ */ new Set();
-  const outputs = readRecord(packaged.outputs) ?? {};
-  for (const outputValue of Object.values(outputs)) {
-    const output2 = readRecord(outputValue);
-    if (output2?.kind !== "dataset") continue;
-    if (typeof output2.datasetId === "string" && output2.datasetId.trim()) {
-      datasetIds.add(output2.datasetId.trim());
-    }
-    for (const candidate of [output2.dataset, output2.path]) {
-      if (typeof candidate === "string" && candidate.trim()) {
-        paths.add(candidate.trim());
-      }
-    }
-  }
-  return { datasetIds, paths };
-}
 function formatRunStepProgress(progress, includeRowOutcomes = false) {
   const executed = readNonNegativeInteger(progress.executed);
   const total = readNonNegativeInteger(progress.total);
@@ -37265,205 +37129,6 @@ function formatRunStepProgress(progress, includeRowOutcomes = false) {
   }
   return parts.join(" \xB7 ");
 }
-function formatPackageDatasetActionLines(packaged, options) {
-  const returned = packageReturnedDatasetIdentity(packaged);
-  const includeSummary = options?.includeSummary ?? true;
-  const lines = [];
-  const steps = readRecordArray(packaged.steps);
-  const stepsByDatasetId = /* @__PURE__ */ new Map();
-  const stepsByPath = /* @__PURE__ */ new Map();
-  const stepsByNamespace = /* @__PURE__ */ new Map();
-  for (const step of steps) {
-    if (step.kind !== "dataset") continue;
-    const output2 = readRecord(step.output);
-    if (typeof output2?.datasetId === "string") {
-      stepsByDatasetId.set(output2.datasetId, step);
-    }
-    if (typeof output2?.path === "string") {
-      stepsByPath.set(output2.path, step);
-    }
-    if (typeof step.id === "string") {
-      stepsByNamespace.set(step.id, step);
-    }
-  }
-  for (const dataset of packageDatasetRecords(packaged)) {
-    const path = typeof dataset.path === "string" && dataset.path.trim() ? dataset.path.trim() : "dataset";
-    const datasetId = typeof dataset.datasetId === "string" ? dataset.datasetId.trim() : "";
-    const isReturned = datasetId && returned.datasetIds.has(datasetId) || returned.paths.has(path);
-    const category = isReturned ? "returned" : dataset.recovered === true ? "recovered" : "persisted";
-    const rowCount = typeof dataset.rowCount === "number" && Number.isFinite(dataset.rowCount) ? Math.max(0, Math.trunc(dataset.rowCount)) : null;
-    const lifecycle = readRecord(dataset.lifecycle);
-    const countUnconfirmed = lifecycle?.complete === false;
-    const persistedLowerBound = typeof lifecycle?.persistedRowsAtLeast === "number" && Number.isFinite(lifecycle.persistedRowsAtLeast) ? Math.max(0, Math.trunc(lifecycle.persistedRowsAtLeast)) : 0;
-    const actions2 = readRecord(dataset.actions) ?? {};
-    if (countUnconfirmed) {
-      lines.push(
-        `  dataset ${path}: row count unconfirmed (at least ${formatInteger(persistedLowerBound)} persisted)`
-      );
-    } else if (includeSummary) {
-      if (category === "recovered" && Object.keys(actions2).length === 0) {
-        lines.push(
-          `  dataset ${path}: available, ${rowCount === null ? "persisted" : formatInteger(rowCount)} rows persisted; re-running reuses completed work`
-        );
-      } else {
-        lines.push(
-          `  ${category} dataset ${path}: ${rowCount === null ? "unknown rows" : `${formatInteger(rowCount)} ${rowCount === 1 ? "row" : "rows"}`}`
-        );
-      }
-    }
-    const step = (datasetId ? stepsByDatasetId.get(datasetId) : void 0) ?? stepsByPath.get(path) ?? (typeof dataset.tableNamespace === "string" ? stepsByNamespace.get(dataset.tableNamespace) : void 0);
-    const progress = readRecord(step?.progress);
-    if (progress) {
-      lines.push(`    progress: ${formatRunStepProgress(progress)}`);
-    }
-    if (lifecycle) {
-      const succeeded = readNonNegativeInteger(lifecycle.succeededRowsAtLeast);
-      const failed = readNonNegativeInteger(lifecycle.failedRowsAtLeast);
-      const complete = lifecycle.complete === true;
-      lines.push(
-        `    saved: ${complete ? "" : "at least "}${formatInteger(persistedLowerBound)} persisted${succeeded === null ? "" : ` \xB7 ${complete ? "" : "at least "}${formatInteger(succeeded)} succeeded`}${failed === null ? "" : ` \xB7 ${complete ? "" : "at least "}${formatInteger(failed)} failed`}`
-      );
-    }
-    const exportAction = readRecord(actions2.exportCsv);
-    const exportCommand = actionToCommand(exportAction);
-    const exportScope = readRecord(exportAction?.scope);
-    const queryAction = readRecord(actions2.query);
-    const queryScope = readRecord(queryAction?.scope);
-    const runQueryCommand = queryScope?.kind === "run" ? actionToCommand(queryAction) : null;
-    const currentQueryCommand = actionToCommand(actions2.queryCurrentTable);
-    const legacyQueryCommand = actionToCommand(actions2.query);
-    if (runQueryCommand) {
-      lines.push(`    query rows from this run: ${runQueryCommand}`);
-    } else if (currentQueryCommand) {
-      lines.push(`    query current table: ${currentQueryCommand}`);
-    } else if (legacyQueryCommand) {
-      lines.push(`    query run rows (legacy): ${legacyQueryCommand}`);
-    }
-    if (exportCommand) {
-      lines.push(
-        exportScope?.kind === "database" ? `    export current table (may include other runs): ${exportCommand}` : `    export this run: ${exportCommand}`
-      );
-    }
-    const unavailable = readRecord(dataset.exportUnavailable);
-    if (typeof unavailable?.reason === "string" && typeof unavailable.message === "string") {
-      lines.push(
-        `    export unavailable (${unavailable.reason}): ${unavailable.message}`
-      );
-    }
-  }
-  return lines;
-}
-function packageSavedRowCount(packaged) {
-  const rowCounts = packageDatasetRecords(packaged).map((dataset) => dataset.rowCount).filter(
-    (rowCount) => typeof rowCount === "number" && Number.isFinite(rowCount)
-  ).map((rowCount) => Math.max(0, Math.trunc(rowCount)));
-  if (rowCounts.length === 0) return null;
-  return rowCounts.reduce((total, rowCount) => total + rowCount, 0);
-}
-function runtimeLimitWindowLabel(runtimeLimitFailure) {
-  const message = getStringField(runtimeLimitFailure, "message") ?? "";
-  const configuredSeconds = /\bconfigured\s+(\d+)\s+second(?:s)?\s+runtime limit\b/i.exec(message)?.[1];
-  if (configuredSeconds) {
-    const seconds = Number(configuredSeconds);
-    if (Number.isSafeInteger(seconds) && seconds > 0) {
-      if (seconds % 3600 === 0) return `${seconds / 3600}-hour`;
-      if (seconds % 60 === 0) return `${seconds / 60}-minute`;
-      return `${seconds}-second`;
-    }
-  }
-  const match = /\b(\d+)\s+(hour|hours|minute|minutes|second|seconds)\b/i.exec(
-    message
-  );
-  if (!match) return "30-minute";
-  const unit = match[2].toLowerCase().replace(/s$/, "");
-  return `${match[1]}-${unit}`;
-}
-function runtimeLimitCheckpointLines(packaged, runId, runtimeLimitFailure) {
-  const savedRows = packageSavedRowCount(packaged);
-  const lines = [
-    `\u2713 progress saved  ${runId}`,
-    "",
-    `The Play reached its ${runtimeLimitWindowLabel(runtimeLimitFailure)} runtime window.`
-  ];
-  if (savedRows === null) {
-    lines.push("Progress completed before the runtime window closed.");
-  } else {
-    lines.push(
-      `${formatInteger(savedRows)} ${savedRows === 1 ? "row was" : "rows were"} saved successfully.`
-    );
-  }
-  lines.push(
-    "",
-    "Run the same Play again to continue where you left off.",
-    "Completed work will be reused automatically."
-  );
-  return lines;
-}
-function formatInlinePackageValue(value) {
-  const compacted = compactReturnValue(value);
-  const json2 = JSON.stringify(compacted);
-  return clampJsonPreviewText(json2 ?? String(compacted), 500);
-}
-function formatPackageValueOutputLines(packaged) {
-  const outputs = packaged.outputs && typeof packaged.outputs === "object" && !Array.isArray(packaged.outputs) ? packaged.outputs : null;
-  if (!outputs) return [];
-  const returned = Object.entries(outputs).filter(([, output2]) => {
-    const record5 = readRecord(output2);
-    return record5?.kind === "dataset" || record5?.kind === "value" && Object.prototype.hasOwnProperty.call(record5, "value");
-  });
-  if (returned.length === 0) return [];
-  const datasets = packageDatasetRecords(packaged);
-  const datasetSteps = readRecordArray(packaged.steps).filter(
-    (step) => step.kind === "dataset"
-  );
-  const lines = ["  result:"];
-  for (const [name, rawOutput] of returned.slice(0, 8)) {
-    const output2 = readRecord(rawOutput);
-    if (output2.kind === "dataset") {
-      const path = typeof output2.dataset === "string" ? output2.dataset : name;
-      const rowCount = readNonNegativeInteger(output2.rowCount);
-      lines.push(
-        `    ${name}: dataset ${path}${rowCount === null ? "" : ` (${formatInteger(rowCount)} persisted rows)`}`
-      );
-      const dataset = datasets.find(
-        (candidate) => typeof output2.datasetId === "string" && candidate.datasetId === output2.datasetId || candidate.path === path
-      );
-      const stepOutput = datasetSteps.map((step) => readRecord(step.output)).find(
-        (candidate) => typeof output2.datasetId === "string" && candidate?.datasetId === output2.datasetId || candidate?.path === path
-      );
-      const preview = readRecord(stepOutput?.preview ?? dataset?.preview);
-      const rows = Array.isArray(preview?.rows) ? preview.rows.slice(0, 2) : [];
-      if (rows.length > 0) {
-        lines.push(`      sample rows (${rows.length}):`);
-        lines.push(
-          ...rows.map(
-            (row) => `        ${clampJsonPreviewText(JSON.stringify(row) ?? String(row), 350)}`
-          )
-        );
-      }
-      continue;
-    }
-    const value = output2.value;
-    const compacted = compactReturnValue(value);
-    if (compacted && typeof compacted === "object") {
-      lines.push(`    ${name}:`);
-      lines.push(...formatJsonPreview(compacted).map((line) => `  ${line}`));
-    } else {
-      lines.push(`    ${name}: ${formatInlinePackageValue(value)}`);
-    }
-  }
-  if (returned.length > 8) {
-    lines.push(`    ... ${returned.length - 8} more output(s)`);
-  }
-  return lines;
-}
-function authoredPackageStackFrames(packaged) {
-  const stack = readRecordArray(packaged.errors).map((entry) => typeof entry.stack === "string" ? entry.stack : null).find((candidate) => Boolean(candidate?.trim()));
-  if (!stack) return [];
-  return stack.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("at ")).filter(
-    (line) => !line.includes("/virtual/deepline-plays/") && !line.includes("/apps/play-runner/") && !line.includes("/shared_libs/play-runtime/") && !line.includes("node:internal")
-  ).slice(0, 5);
-}
 function activityTargetLabel(target) {
   const kind = typeof target.kind === "string" ? target.kind : "target";
   const label = typeof target.label === "string" ? target.label.trim() : "";
@@ -37619,152 +37284,6 @@ function formatRunTimingTextLines(run) {
     ].join(" \xB7 ")}`
   ];
 }
-function formatRecentRunLogLines(value) {
-  const logs = readRecord(value);
-  if (!logs || !Array.isArray(logs.tail)) return [];
-  const tail = logs.tail.filter(
-    (line) => typeof line === "string"
-  );
-  if (tail.length === 0) return [];
-  const shown = tail.map((line) => classifyLogLine(line)).filter(
-    (entry) => entry.level !== "debug" && !isProviderRowWaitLogLine(entry.line)
-  ).slice(-8);
-  const total = readNonNegativeInteger(logs.totalCount);
-  if (shown.length === 0) {
-    return [
-      `  recent logs: no non-debug lines in the retained preview (${total === null ? "total unknown" : `${formatInteger(total)} total`})`,
-      ...logs.truncated === true ? ["    [older log bodies lost to retention limit]"] : []
-    ];
-  }
-  const lines = [
-    `  recent logs (${total === null ? "count unknown" : `${formatInteger(total)} total`}; showing ${shown.length}):`,
-    ...shown.map(
-      (entry) => `    ${clampJsonPreviewText(formatProviderCapacityWaitLogLine(entry.line) ?? formatMapProgressDiagnosticLogLine(entry.line) ?? entry.line, 350)}`
-    )
-  ];
-  if (logs.truncated === true) {
-    lines.push("    [older log bodies lost to retention limit]");
-  }
-  return lines;
-}
-function buildRunPackageTextLines(packaged) {
-  const run = readRunPackageRun(packaged);
-  const runId = typeof run.id === "string" ? run.id : "unknown";
-  const status = typeof run.status === "string" ? run.status : "unknown";
-  const playName = typeof run.playName === "string" ? run.playName : null;
-  const runtimeLimitFailure = readRecordArray(packaged.errors).find(
-    (entry) => entry.code === "RUNTIME_LIMIT_EXCEEDED"
-  );
-  const isRuntimeTimeout = status === "failed" && (runtimeLimitFailure !== void 0 || typeof run.error === "string" && /RUNTIME_LIMIT_EXCEEDED/.test(run.error));
-  const isRuntimeLimitCheckpoint = isRuntimeTimeout;
-  const checkpointFailure = runtimeLimitFailure ?? (typeof run.error === "string" ? { message: run.error } : { message: "The Play reached its runtime limit and was stopped." });
-  const lines = isRuntimeLimitCheckpoint ? runtimeLimitCheckpointLines(packaged, runId, checkpointFailure) : [
-    `${status === "completed" ? "\u2713" : status === "failed" ? "\u2717" : "\u2022"} ${status}  ${runId}`
-  ];
-  const outcome = typeof run.outcome === "string" ? run.outcome : null;
-  if (outcome) lines.push(`  outcome: ${outcome}`);
-  const recovery = readRecord(run.recovery);
-  if (recovery) {
-    const mode = typeof recovery.mode === "string" ? recovery.mode : "recovered";
-    const sourceRunId = typeof recovery.sourceRunId === "string" ? ` from ${recovery.sourceRunId}` : "";
-    lines.push(`  recovery: ${mode}${sourceRunId}`);
-  }
-  const runError = typeof run.error === "string" && run.error.trim() ? run.error.trim() : null;
-  const structuredRuntimeLimitMessage = typeof runtimeLimitFailure?.message === "string" && runtimeLimitFailure.message.trim() ? `${typeof runtimeLimitFailure.code === "string" ? runtimeLimitFailure.code : "RUNTIME_LIMIT_EXCEEDED"}: ${runtimeLimitFailure.message.trim()}` : null;
-  const displayRunError = structuredRuntimeLimitMessage ?? runError;
-  if (!isRuntimeLimitCheckpoint && displayRunError && (status === "failed" || status === "cancelled")) {
-    lines.push(`  error: ${truncateErrorForDisplay(displayRunError, runId)}`);
-    const stackFrames = authoredPackageStackFrames(packaged);
-    if (stackFrames.length > 0) {
-      lines.push("  stack:");
-      lines.push(...stackFrames.map((frame) => `    ${frame}`));
-    }
-  }
-  const failedLogs = readRecord(packaged.failedLogs);
-  const failedLogEntries = Array.isArray(failedLogs?.entries) ? failedLogs.entries.filter(
-    (entry) => typeof entry === "string"
-  ) : [];
-  const failedLogAssociation = typeof failedLogs?.association === "string" ? failedLogs.association : null;
-  const failedLogWarning = typeof failedLogs?.warning === "string" && failedLogs.warning.trim() ? failedLogs.warning.trim() : null;
-  if (failedLogEntries.length > 0) {
-    lines.push("  failed logs:");
-    lines.push(...failedLogEntries.map((entry) => `    ${entry}`));
-  }
-  if (failedLogAssociation === "retained_before_truncation") {
-    lines.push("  failed log context: last retained lines before truncation");
-  }
-  if (failedLogWarning) {
-    lines.push(`  warning: ${failedLogWarning}`);
-  }
-  const packageWarnings = Array.isArray(packaged.warnings) ? Array.from(
-    new Set(
-      packaged.warnings.filter(
-        (warning) => typeof warning === "string" && warning.trim().length > 0
-      )
-    )
-  ).slice(0, 16) : [];
-  lines.push(...packageWarnings.map((warning) => `  warning: ${warning}`));
-  const failedLogNext = readRecord(failedLogs?.next);
-  if (failedLogWarning && typeof failedLogNext?.logs === "string") {
-    lines.push(
-      failedLogAssociation === "retained_before_truncation" ? `  retained logs: ${failedLogNext.logs}` : `  retry failed logs: ${failedLogNext.logs}`
-    );
-  }
-  if (playName && !isRuntimeLimitCheckpoint) {
-    lines.push(`  play: ${playName}`);
-  }
-  lines.push(...formatRunTimingTextLines(run));
-  if (!isRuntimeLimitCheckpoint) {
-    lines.push(...buildRunActivityTextLines(run));
-  }
-  lines.push(...buildRunStatusEvidenceTextLines(packaged));
-  lines.push(...formatPackageValueOutputLines(packaged));
-  lines.push(
-    ...formatPackageDatasetActionLines(packaged, {
-      includeSummary: !isRuntimeLimitCheckpoint
-    })
-  );
-  lines.push(...formatRecentRunLogLines(packaged.logs));
-  const next = packaged.next && typeof packaged.next === "object" && !Array.isArray(packaged.next) ? packaged.next : {};
-  const logsCommand = actionToCommand(next.logs);
-  for (const step of isRuntimeLimitCheckpoint ? [] : readRecordArray(packaged.steps).slice(0, 8)) {
-    const id = typeof step.id === "string" ? step.id : "step";
-    const kind = typeof step.kind === "string" ? step.kind : "step";
-    const stepStatus = typeof step.status === "string" ? step.status : status;
-    const output2 = step.output && typeof step.output === "object" && !Array.isArray(step.output) ? step.output : null;
-    const rowCount = output2 && typeof output2.rowCount === "number" ? ` rows=${formatInteger(output2.rowCount)}` : "";
-    const preview = output2?.preview && typeof output2.preview === "object" && !Array.isArray(output2.preview) ? output2.preview : null;
-    const previewRows = Array.isArray(preview?.rows) ? preview.rows.length : null;
-    lines.push(`  ${kind} ${id}: ${stepStatus}${rowCount}`);
-    lines.push(...formatPackageDatasetSummaryLines(output2?.summary));
-    if (previewRows !== null) {
-      lines.push(
-        `    preview=${previewRows}${preview?.truncated ? " truncated" : ""}`
-      );
-    }
-  }
-  const inspectCommand = actionToCommand(next.inspect);
-  const fullResultCommand = actionToCommand(next.full);
-  const hasCatalogExportAction = packageDatasetRecords(packaged).some(
-    (dataset) => Boolean(actionToCommand(readRecord(dataset.actions)?.exportCsv))
-  );
-  const legacyExportCommand = hasCatalogExportAction ? null : actionToCommand(next.export);
-  const runAgainCommand = typeof next.run === "string" && next.run.trim() ? next.run.trim() : null;
-  if (inspectCommand) lines.push(`  inspect: ${inspectCommand}`);
-  if (fullResultCommand)
-    lines.push(
-      `  ${isRuntimeTimeout ? "full run details" : "full result"}: ${fullResultCommand}`
-    );
-  if (logsCommand) lines.push(`  logs: ${logsCommand}`);
-  if (legacyExportCommand) {
-    lines.push(`  export CSV: ${legacyExportCommand}`);
-  }
-  if (runAgainCommand && !isRuntimeLimitCheckpoint) {
-    lines.push("  run again (completed work is reused):");
-    lines.push(`    ${runAgainCommand}`);
-  }
-  return lines;
-}
 function buildOrdinaryPlayRunCommand(options, resolvedRevisionId) {
   const target = options.target.kind === "file" ? options.target.path : options.target.name;
   const parts = ["deepline", "plays", "run", shellSingleQuote(target)];
@@ -37850,6 +37369,57 @@ function buildRunLaunch(status) {
     )
   };
 }
+function buildPlayCompletionTextLines(status) {
+  const overview = buildRunOverview(status);
+  const { run } = overview;
+  const failed = run.status === "failed";
+  const label = run.status === "completed" ? overview.rowOutcomes?.hasRowFailures ? "Completed with row failures" : "Completed" : failed ? "Failed" : run.status;
+  const lines = [
+    `${label} ${run.playName ?? status.playName ?? "Play"}`,
+    `Run: ${run.id}`
+  ];
+  for (const failure of overview.failures.steps) {
+    lines.push(
+      `Failed step: ${failure.stepId}${failure.message ? ` \u2014 ${failure.message}` : ""}`
+    );
+  }
+  if (overview.errorDetails.run)
+    lines.push(
+      `Error: ${truncateErrorForDisplay(overview.errorDetails.run, run.id)}`
+    );
+  if (Object.hasOwn(overview, "result")) {
+    lines.push(
+      "Result:",
+      ...formatJsonPreview(compactReturnValue(overview.result))
+    );
+  }
+  if (overview.rowOutcomes?.hasRowFailures) {
+    lines.push(
+      `Rows: ${overview.rowOutcomes.completedRows} completed, ${overview.rowOutcomes.failedRows} failed`
+    );
+  }
+  for (const dataset of overview.datasets) {
+    lines.push(
+      `Rows (${dataset.name ?? dataset.datasetId}): ${dataset.rowCount ?? "unknown"}`
+    );
+    if (dataset.exportUnavailable)
+      lines.push(`Export unavailable: ${dataset.exportUnavailable.message}`);
+  }
+  for (const warning of overview.warnings) lines.push(`Warning: ${warning}`);
+  const exports2 = overview.actions.exportDatasetCmds;
+  if (Array.isArray(exports2))
+    for (const command of exports2) lines.push(`Export CSV: ${command}`);
+  lines.push(
+    `Logs: ${failed ? String(
+      overview.actions.getFailedLogsCmd ?? `deepline runs logs ${shellSingleQuote(run.id)} --failed`
+    ) : String(
+      overview.actions.getLogsCmd ?? `deepline runs logs ${shellSingleQuote(run.id)}`
+    )}`
+  );
+  if (failed && status.rerunCommand)
+    lines.push(`Retry: ${status.rerunCommand}`);
+  return lines;
+}
 function writePlayResult(status, jsonOutput, options) {
   const packaged = getPlayRunPackage(status);
   const hits = options?.hits ?? null;
@@ -37868,10 +37438,7 @@ function writePlayResult(status, jsonOutput, options) {
       ...displayPackage
     } = compactPlayStatus(status);
     const lines2 = [
-      ...withRunNavigationLines(
-        buildRunPackageTextLines(displayPackage),
-        status
-      ),
+      ...buildPlayCompletionTextLines(status),
       ...formatRunHitsLines(hits)
     ];
     printCommandEnvelope(displayPackage, {
@@ -37907,7 +37474,7 @@ function writePlayResult(status, jsonOutput, options) {
     )
   );
   if (status.status === "failed") {
-    lines.push(`  failed logs: deepline runs get ${runId} --log-failed --json`);
+    lines.push(`  failed logs: deepline runs logs ${runId} --failed --json`);
     if (status.rerunCommand) {
       lines.push("  run again (completed work is reused):");
       lines.push(`    ${status.rerunCommand}`);
@@ -37937,18 +37504,23 @@ function writePlayResult(status, jsonOutput, options) {
   );
 }
 function withRunNavigationLines(lines, status, actionCommands = buildRunNavigation(status).actions) {
-  const navigation = buildRunNavigation(status);
   const existing = lines.join("\n");
-  for (const dataset of navigation.datasets) {
-    if (dataset.storage.table)
-      lines.push(
-        `  dataset ${dataset.name}: ${dataset.storage.schema ? dataset.storage.schema + "." : ""}${dataset.storage.table}`
-      );
-  }
+  const labels = {
+    getRunCmd: "Inspect",
+    getFullRunCmd: "Full run",
+    getBillingCmd: "Billing",
+    getLogsCmd: "Logs",
+    getFailedLogsCmd: "Failure logs",
+    getReceiptCmd: "Saved responses",
+    exportDatasetCmds: "Export rows",
+    queryTableSqlCmds: "Query rows",
+    stopRunCmd: "Stop run",
+    rerunCmd: "Retry"
+  };
   for (const [name, value] of Object.entries(actionCommands)) {
     for (const command of Array.isArray(value) ? value : [value]) {
       if (typeof command === "string" && !existing.includes(command))
-        lines.push(`  ${name}: ${command}`);
+        lines.push(`  ${labels[name] ?? name}: ${command}`);
     }
   }
   return lines;
@@ -38691,7 +38263,12 @@ function writeStartedPlayRun(input2) {
       failedLogs: _failedLogs,
       ...displayPackage
     } = input2.package;
-    const lines2 = buildRunPackageTextLines(displayPackage);
+    const lines2 = buildPlayCompletionTextLines({
+      runId: input2.runId,
+      playName: input2.playName,
+      status: input2.status,
+      package: displayPackage
+    });
     const output3 = lines2.join("\n");
     if (input2.progress) {
       input2.progress.writeLine(output3, process.stdout);
@@ -38719,17 +38296,11 @@ function writeStartedPlayRun(input2) {
   };
   const lines = [
     `Started ${input2.playName}`,
-    `  run id: ${input2.runId}`,
-    `  revision: ${input2.revisionLabel ?? "resolved by Deepline"}`,
-    `  input: ${input2.inputFieldCount ?? 0} top-level field(s) supplied`,
-    `  cache: ${input2.forceToolRefresh ? "completed provider receipts may be refreshed" : input2.force ? "fresh run graph; completed provider receipts may still be reused" : "completed provider receipts may be reused"}`,
-    `  inspect: deepline runs get ${input2.runId} --json`,
-    `  full debug: deepline runs get ${input2.runId} --full --json`,
-    `  logs: deepline runs logs ${input2.runId} --json`,
-    `  export after completion: deepline runs export ${input2.runId} --out output.csv`,
+    `Run: ${input2.runId}`,
+    `Logs: deepline runs logs ${shellSingleQuote(input2.runId)}`,
     ...["started", "queued", "running", "waiting"].includes(
       input2.status ?? "started"
-    ) ? [`  stop run: deepline runs stop ${input2.runId} --json`] : []
+    ) ? [`Stop: deepline runs stop ${shellSingleQuote(input2.runId)} --json`] : []
   ];
   if (input2.jsonOutput) {
     printCommandEnvelope(payload, { json: true, fields: input2.jsonFields });
@@ -40151,7 +39722,7 @@ function renderRunOverviewText(overview, extras = {}) {
     getBillingCmd: "Billing",
     getLogsCmd: "Logs",
     getFailedLogsCmd: "Failure logs",
-    getReceiptCmd: "Receipt",
+    getReceiptCmd: "Saved responses",
     exportDatasetCmds: "Export rows",
     queryTableSqlCmds: "Query rows",
     stopRunCmd: "Stop run",
@@ -40173,7 +39744,7 @@ async function handleRunGet(args) {
     args.includes("--config") ? "config" : "get"
   );
   args = selection.args;
-  const usage2 = "Usage: deepline runs get <run-id> [--json] [--full] [--input] [--config] [--log-failed]";
+  const usage2 = "Usage: deepline runs get <run-id> [--json] [--full] [--input] [--config]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage2);
@@ -43182,7 +42753,7 @@ Examples:
   deepline runs get play/my-play/run/20260501t000000-000
   deepline runs get play/my-play/run/20260501t000000-000 --json
   deepline runs get play/my-play/run/20260501t000000-000 --json run.status,run.durationMs
-  deepline runs get play/my-play/run/20260501t000000-000 --log-failed --json
+  deepline runs logs play/my-play/run/20260501t000000-000 --failed --json
   deepline runs get play/my-play/run/20260501t000000-000 --full --json
   deepline runs get play/my-play/run/20260501t000000-000 --input
   deepline runs get play/my-play/run/20260501t000000-000 --config --json
@@ -43199,9 +42770,8 @@ Examples:
   ).option(
     "--config",
     "Explicitly print the recorded configuration, without full results"
-  ).option(
-    "--log-failed",
-    "Attach a bounded terminal-failure log window for failed runs"
+  ).addOption(
+    new import_commander4.Option("--log-failed", "Attach terminal-failure logs").hideHelp()
   ).action(async (runId, options) => {
     process.exitCode = await handleRunGet([
       runId,
@@ -50587,7 +50157,10 @@ Examples:
     `
 Notes:
   Shows the compact agent contract by default: what the tool does, cost,
-  required inputs, play getters, and a runnable ctx.tools.execute snippet.
+  required inputs, play getters, input and full Deepline response examples,
+  and a ctx.tools.execute snippet. Tool responses live at toolResponse.rawV2;
+  preserve the nesting shown in the tool's example. Schemas and examples are
+  separate describe fields.
   get is accepted as a compatibility alias for describe.
 
 Examples:
@@ -50610,7 +50183,7 @@ Examples:
     "Quote an ai_evaluate, ai_inference, or deeplineagent JSON payload (inline or @file)"
   ).option("--pricing-only", "Only print pricing and billing semantics").option("--schema-only", "Only print input schema fields").option(
     "--examples-only",
-    "Only print runnable examples and sample payloads"
+    "Only print input payload and full Deepline execution response examples"
   ).option("--getters-only", "Only print extracted list/value getters").addOption(
     new import_commander5.Option(
       "--compact",
@@ -50787,6 +50360,30 @@ async function getTool(toolId, options = {}) {
     );
     return 0;
   }
+  if ((options.schemaOnly || options.examplesOnly || options.gettersOnly) && !isMonitorTypeTool(tool) && !isPlayLikeTool(tool) && (options.json || options.contractJson)) {
+    const contract = toolContractJsonForDescribe(tool, toolId);
+    printCompactJson({
+      toolId: contract.toolId,
+      ...options.schemaOnly ? {
+        inputSchema: contract.inputSchema,
+        inputFields: contract.inputFields,
+        outputSchema: contract.outputSchema,
+        outputFields: contract.outputFields,
+        responseSchema: contract.responseSchema
+      } : options.examplesOnly ? {
+        examples: contract.examples ?? [],
+        responseAccess: contract.responseAccess,
+        getters: contract.getters,
+        executeCommand: contract.executeCommand
+      } : {
+        getters: contract.getters,
+        responseAccess: contract.responseAccess
+      },
+      ...modelDescription ? { modelOptions: modelDescription } : {},
+      ...inferenceQuote ? { inferenceQuote } : {}
+    });
+    return 0;
+  }
   if (options.contractJson) {
     printCompactJson({
       ...toolContractJsonForDescribe(tool, toolId),
@@ -50928,6 +50525,9 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
     } : {},
     inputFields: inputFields.map(inputFieldJsonForDescribe),
     inputSchema,
+    ...isRecord8(tool.responseSchema) ? { responseSchema: tool.responseSchema } : {},
+    ...Array.isArray(tool.examples) ? { examples: tool.examples } : {},
+    responseAccess: "result.toolResponse.rawV2",
     ...Object.keys(outputSchemaRecord).length > 0 ? {
       outputSchema: publicToolInputSchemaForDescribe(outputSchemaRecord),
       outputFields: outputFields.map(inputFieldJsonForDescribe)
@@ -51149,15 +50749,13 @@ function printCompactToolContract(tool, requestedToolId) {
     }
   }
   console.log("");
-  printToolExamplesOnly(tool, requestedToolId, { includeSamples: false });
+  printToolExamplesOnly(tool, requestedToolId);
   const starterScript = isRecord8(contract.starterScript) ? contract.starterScript : {};
   const starterPath = stringField2(starterScript, "path");
   if (starterPath) {
     console.log("");
     console.log(`Starter script: ${starterPath}`);
-    console.log(
-      "Copy it into your project and replace the sample input with the proven probe payload."
-    );
+    console.log("Copy it into your project and adapt the example input.");
   }
   if (listGetters.length || valueGetters.length) {
     console.log("");
@@ -51247,11 +50845,15 @@ function printToolSchemaOnly(tool, requestedToolId) {
     recordField(contract, "inputSchema")
   );
   if (declaredSchema) {
-    console.log("Declared JSON Schema:");
+    console.log("Declared input JSON Schema:");
     console.log(JSON.stringify(declaredSchema, null, 2));
   }
+  if (isRecord8(contract.responseSchema)) {
+    console.log("Deepline execution response JSON Schema:");
+    console.log(JSON.stringify(contract.responseSchema, null, 2));
+  }
 }
-function printToolExamplesOnly(tool, requestedToolId, options = {}) {
+function printToolExamplesOnly(tool, requestedToolId) {
   if (isMonitorTypeTool(tool)) {
     printMonitorTypeDeploy(tool);
     return;
@@ -51263,7 +50865,11 @@ function printToolExamplesOnly(tool, requestedToolId, options = {}) {
   const contract = toolContractJsonForDescribe(tool, requestedToolId);
   const toolId = String(contract.toolId);
   const inputFields = Array.isArray(contract.inputFields) ? contract.inputFields : [];
-  const sampleInput = samplePayloadForInputFields(inputFields);
+  const examples = arrayField2(tool, "examples").filter(isRecord8);
+  const firstExample = examples[0];
+  const sampleInput = firstExample && isRecord8(firstExample.input) ? firstExample.input : samplePayload(recordField(tool, "samples"), "request") ?? samplePayloadForInputFields(inputFields);
+  console.log("Example input payload:");
+  console.log(JSON.stringify(sampleInput, null, 2));
   console.log(`Use in a play:`);
   console.log("```ts");
   console.log("const result = await ctx.tools.execute({");
@@ -51273,6 +50879,7 @@ function printToolExamplesOnly(tool, requestedToolId, options = {}) {
     `  input: ${JSON.stringify(sampleInput || {}, null, 2).replace(/\n/g, "\n  ")},`
   );
   console.log("});");
+  console.log("const response = result.toolResponse.rawV2;");
   const getters = isRecord8(contract.getters) ? contract.getters : {};
   const valueGetters = Array.isArray(getters.extractedValues) ? getters.extractedValues : [];
   const listGetters = Array.isArray(getters.extractedLists) ? getters.extractedLists : [];
@@ -51286,10 +50893,19 @@ function printToolExamplesOnly(tool, requestedToolId, options = {}) {
       );
   }
   console.log("```");
-  if (options.includeSamples !== false) {
-    const samples = recordField(tool, "samples");
-    printSamples(samples);
+  for (const example of examples) {
+    const description = stringField2(example, "description");
+    if (description) console.log(description);
+    console.log("Example Deepline execution response:");
+    console.log(JSON.stringify(example.response, null, 2));
   }
+  if (!examples.length)
+    console.log(
+      "No Deepline execution response example is published by this server."
+    );
+  console.log(
+    "Read tool-specific fields from result.toolResponse.rawV2 using the nesting above. In a play, use the declared getters for extracted values and lists. Billing and execution metadata may also be returned."
+  );
 }
 function printPlayLikeToolUsage(tool, requestedToolId) {
   const toolId = String(tool.toolId || requestedToolId);
@@ -51434,9 +51050,9 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
     inputFields: inputFields.map(inputFieldJsonForDescribe),
     usageGuidance,
     runtimeOutputHelp: {
-      contract: "tools describe shows declared schema and Deepline getters; it is not an observed provider response.",
+      contract: "Schemas declare field shapes. Examples illustrate input payloads and full Deepline execution responses; they are not observed responses from this call.",
       getterScope: "extractedValues/extractedLists .get() only works for declared Deepline getters listed in usageGuidance.toolExecutionResult.",
-      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().",
+      rawToolResponse: "Use toolExecutionResult.toolResponse.rawV2 for the complete tool response. Preserve its nesting and sibling fields as shown in examples; use declared getters for extracted values and lists.",
       invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter.",
       observeActualShape: observedOutputCommand,
       observedOutput: observedOutputCommand,
@@ -51451,7 +51067,25 @@ function usageGuidanceWithAccessDefaults(usageGuidance) {
   const existingAccess = recordField(usageGuidance, "access");
   return {
     ...usageGuidance,
+    prefer: [
+      "Use only the declared extractedLists and extractedValues getters listed below.",
+      "Use toolExecutionResult.toolResponse.rawV2 for the complete tool response, preserving the nesting shown in the response example.",
+      "Schemas declare field shapes; examples illustrate input values and full Deepline execution responses."
+    ],
+    toolExecutionResult: {
+      ...recordField(
+        usageGuidance,
+        "toolExecutionResult",
+        "tool_execution_result"
+      ),
+      toolResponse: {
+        rawV2: "toolResponse.rawV2",
+        view: "toolResponse.view",
+        responseMeta: "toolResponse.responseMeta"
+      }
+    },
     access: {
+      ...existingAccess,
       extractedLists: {
         expression: "toolExecutionResult.extractedLists.<name>.get()",
         meaning: "Declared Deepline list extractors only."
@@ -51463,13 +51097,13 @@ function usageGuidanceWithAccessDefaults(usageGuidance) {
       ...existingAccess,
       rawToolResponse: {
         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()."
+        meaning: "Complete tool response with its original nesting. Read tool-specific fields here; use declared getters for extracted values and lists."
       },
       canonicalToolResponse: {
         expression: "toolExecutionResult.toolResponse.rawV2",
-        meaning: "Complete parsed and scrubbed provider response, including envelope siblings, pagination, and metadata."
+        meaning: "Complete tool response with its original nesting and sibling fields."
       },
-      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."
+      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; read it from toolResponse.rawV2 using the nesting shown in the response example."
     }
   };
 }
@@ -51801,23 +51435,6 @@ function formatRateWindow(windowMs) {
   if (windowMs === 36e5) return "hour";
   return `${windowMs}ms`;
 }
-function printSamples(samples) {
-  const requestPayload = samplePayload(samples, "request");
-  const responsePayload = samplePayload(samples, "response");
-  if (requestPayload === void 0 && responsePayload === void 0) return;
-  console.log("  Samples:");
-  if (requestPayload !== void 0)
-    printJsonPreview("Example payload", requestPayload);
-  if (responsePayload !== void 0)
-    printJsonPreview("Example response", responsePayload);
-}
-function printJsonPreview(label, payload) {
-  console.log(`  ${label}:`);
-  const rendered = JSON.stringify(payload, null, 2);
-  for (const line of rendered.split("\n")) {
-    console.log(`    ${line}`);
-  }
-}
 function samplePayload(samples, key) {
   const entry = samples[key];
   if (!isRecord8(entry)) return void 0;
@@ -52430,9 +52047,13 @@ async function executeTool(args) {
   }).catch((error) => {
     const guidanceLines = toolGuidanceLines(metadata.guidance);
     if (guidanceLines.length > 0) {
-      console.error(
-        [`Guidance for ${parsed.toolId}:`, ...guidanceLines].join("\n")
-      );
+      if (args.includes("--json") && error instanceof Error) {
+        Object.assign(error, { guidance: metadata.guidance });
+      } else {
+        console.error(
+          [`Guidance for ${parsed.toolId}:`, ...guidanceLines].join("\n")
+        );
+      }
     }
     throw error;
   });