deepline 0.3.65 → 0.3.66

package/dist/bundling-sources/sdk/src/release.ts

@@ -199,7 +199,7 @@ export const SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: '0.3.65',
+  version: '0.3.66',
   updateSummary:
     'Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -194,6 +194,10 @@ import {
   type PlayAuthoringRunScope,
   type PlayAuthoringRuntimeContext,
 } from '../plays/authoring-contract';
+import {
+  formatCtxFetchHttpFailureDiagnostic,
+  tagLogProvenance,
+} from './log-provenance';
 import {
   DURABLE_RECEIPT_WAIT_DELAY_MS,
   DURABLE_RECEIPT_WAIT_MAX_ATTEMPTS,
@@ -451,6 +455,10 @@ const DEFAULT_TOOL_RUNTIME_TIMEOUT_MS = 15 * 60 * 1000 + 30_000;
 const FETCH_TRANSPORT_MAX_ATTEMPTS =
   RUNTIME_RELIABILITY_POLICY.egress.fetchMaxAttempts;
 const FETCH_TRANSPORT_RETRY_DELAY_MS = 100;
+// Diagnostic logs are retained in the context until terminalization. Keep a
+// representative, deduplicated set so row-heavy continued failures cannot turn
+// customer-safe observability into unbounded runner memory or log traffic.
+const MAX_CTX_FETCH_HTTP_FAILURE_DIAGNOSTICS = 16;
 const CTX_FETCH_HEADERS_TIMEOUT_MS =
   RUNTIME_RELIABILITY_POLICY.egress.fetchHeadersTimeoutMs;
 const CTX_FETCH_BODY_TIMEOUT_MS =
@@ -2087,6 +2095,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   #options: ContextOptions;
   private readonly executionScope: RunExecutionScope;
   private logBuffer: string[] = [];
+  private readonly ctxFetchHttpFailureDiagnosticIdentities = new Set<string>();
   private checkpoint: PlayCheckpoint;
   private readonly durableCallCacheEpochMs: number;
   /**
@@ -10160,6 +10169,58 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     if (this.#options.verbose) console.log(line);
   }
 
+  /**
+   * Emit a runtime-authored diagnostic through the same durable log path as
+   * ctx.log without changing the customer-authored log wire format.
+   */
+  private runtimeDiagnosticLog(message: string): void {
+    assertNoSecretTaint(message, 'runtime diagnostic log');
+    const line = tagLogProvenance(
+      'diagnostic',
+      `[${new Date().toISOString()}] ${this.secretRedactor.redactRegisteredSecrets(message)}`,
+    );
+    this.logBuffer.push(line);
+    this.#options.onLog?.(line);
+    if (this.#options.verbose) console.log(line);
+  }
+
+  /** A URL safe to persist in a customer-visible run log (origin only). */
+  private ctxFetchDiagnosticUrl(url: string): string {
+    try {
+      const parsed = new URL(url);
+      return parsed.origin;
+    } catch {
+      // ctx.fetch already parses its URL before this helper is reachable.
+      return '[invalid-url]';
+    }
+  }
+
+  private logCtxFetchHttpFailure(input: {
+    key: string;
+    method: string;
+    url: string;
+    httpStatus: number;
+  }): void {
+    const url = this.ctxFetchDiagnosticUrl(input.url);
+    const identity = `${input.key}\u0000${input.method}\u0000${url}\u0000${input.httpStatus}`;
+    if (
+      this.ctxFetchHttpFailureDiagnosticIdentities.has(identity) ||
+      this.ctxFetchHttpFailureDiagnosticIdentities.size >=
+        MAX_CTX_FETCH_HTTP_FAILURE_DIAGNOSTICS
+    ) {
+      return;
+    }
+    this.ctxFetchHttpFailureDiagnosticIdentities.add(identity);
+    this.runtimeDiagnosticLog(
+      formatCtxFetchHttpFailureDiagnostic({
+        key: input.key,
+        method: input.method,
+        url,
+        http_status: input.httpStatus,
+      }),
+    );
+  }
+
   async sleep(ms: number): Promise<void> {
     this.assertInlineChildContract('suspending_child');
     const delayMs =
@@ -10212,6 +10273,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
     const url = input.toString();
     const parsedUrl = new URL(url);
+    const method = (init.method ?? 'GET').toUpperCase();
     const urlContainsResolvedSecret =
       this.secretRedactor.containsRegisteredSecret(url, {
         includeEncoded: true,
@@ -10303,6 +10365,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         staleAfterSeconds: options?.staleAfterSeconds,
         transient: options?.transient === true,
         onRecovered: (output) => {
+          if (!output.ok) {
+            this.logCtxFetchHttpFailure({
+              key: normalizedKey,
+              method,
+              url: output.url || url,
+              httpStatus: output.status,
+            });
+          }
           if (!output.ok && this.currentAuthoringContractEdition >= 5) {
             throw new CtxFetchHttpError(output);
           }
@@ -10314,7 +10384,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             this.currentAuthoringContractEdition >= 5
           ),
         execute: async ({ retainExternalCallSlot }) => {
-          const method = (init.method ?? 'GET').toUpperCase();
           const secretHeaders = await this.resolveSecretAuth(secretAuth);
           const headers: Record<string, string> = {
             ...normalizeFetchHeaders(init.headers),
@@ -10349,6 +10418,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             'output' in existing
           ) {
             this.log(`ctx.fetch(${url}): recovered response from checkpoint`);
+            const checkpointOutput = existing.output as PlayFetchResponse;
+            if (!checkpointOutput.ok) {
+              this.logCtxFetchHttpFailure({
+                key: normalizedKey,
+                method,
+                url: checkpointOutput.url || url,
+                httpStatus: checkpointOutput.status,
+              });
+            }
             if (this.durableDirectToolResultsBackedByReceipts) {
               // The outer durable receipt is the replay authority in hosted
               // runtimes. A legacy checkpoint fetch may seed that receipt
@@ -10356,7 +10434,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               // cache for the lifetime of a large map.
               delete this.checkpoint.resolvedBoundaries?.[boundaryId];
             }
-            return existing.output as PlayFetchResponse;
+            return checkpointOutput;
           }
 
           if (!['GET', 'HEAD', 'OPTIONS'].includes(method)) {
@@ -10496,6 +10574,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               json: this.secretRedactor.redactKnownSecrets(rawJson),
             };
 
+            if (!output.ok) {
+              this.logCtxFetchHttpFailure({
+                key: normalizedKey,
+                method,
+                url: output.url || url,
+                httpStatus: output.status,
+              });
+            }
+
             // Edition 5 adopts normal fetch semantics: a non-2xx response is
             // a failed durable operation. Throw before checkpoint/receipt
             // completion so the failure is never cached. Editions 1–4 retain

package/dist/bundling-sources/shared_libs/play-runtime/log-provenance.ts

@@ -125,6 +125,85 @@ export function tagLogProvenance(
   return `${PROVENANCE_PREFIX}${provenance}${PROVENANCE_SENTINEL}${line}`;
 }
 
+/**
+ * A customer-safe record of a `ctx.fetch` response that reached the server but
+ * was not successful. Its URL is destination-origin-only; it deliberately
+ * omits paths, query strings, request/response bodies, headers, receipt ids,
+ * and row identity: all of those can contain customer data or credentials.
+ * This one stable shape is shared by the
+ * runtime (emission), finalization (terminal warning), and CLI/tests
+ * (inspection), rather than each layer trying to infer an HTTP failure from
+ * arbitrary user logs.
+ */
+export type CtxFetchHttpFailureDiagnostic = {
+  key: string;
+  method: string;
+  url: string;
+  http_status: number;
+};
+
+/** Guard terminal-transport diagnostics before they reach customer surfaces. */
+export function isCtxFetchHttpFailureDiagnostic(
+  value: unknown,
+): value is CtxFetchHttpFailureDiagnostic {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.key === 'string' &&
+    typeof record.method === 'string' &&
+    typeof record.url === 'string' &&
+    typeof record.http_status === 'number' &&
+    Number.isInteger(record.http_status)
+  );
+}
+
+export const CTX_FETCH_HTTP_FAILURE_LOG_PREFIX =
+  '[runtime.ctx_fetch_http_failure]';
+
+/** Format the canonical durable log line for an observed non-2xx ctx.fetch. */
+export function formatCtxFetchHttpFailureDiagnostic(
+  diagnostic: CtxFetchHttpFailureDiagnostic,
+): string {
+  return `${CTX_FETCH_HTTP_FAILURE_LOG_PREFIX} ${JSON.stringify(diagnostic)}`;
+}
+
+/**
+ * Parse only runtime-authored, canonical ctx.fetch diagnostics. Untagged
+ * legacy/user lines are never interpreted as evidence, even if they happen to
+ * contain the same words.
+ */
+export function parseCtxFetchHttpFailureDiagnostic(
+  rawLine: string,
+): CtxFetchHttpFailureDiagnostic | null {
+  const tagged = readProvenanceTag(rawLine);
+  if (tagged.provenance !== 'diagnostic') return null;
+  const index = tagged.line.indexOf(CTX_FETCH_HTTP_FAILURE_LOG_PREFIX);
+  if (index === -1) return null;
+  const json = tagged.line
+    .slice(index + CTX_FETCH_HTTP_FAILURE_LOG_PREFIX.length)
+    .trim();
+  try {
+    const parsed: unknown = JSON.parse(json);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return null;
+    }
+    const record = parsed as Record<string, unknown>;
+    if (!isCtxFetchHttpFailureDiagnostic(record)) {
+      return null;
+    }
+    return {
+      key: record.key,
+      method: record.method,
+      url: record.url,
+      http_status: record.http_status,
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Read a structural provenance tag off a line, if present, and return the tag
  * plus the original untagged line. Returns `null` provenance when untagged.
@@ -141,9 +220,7 @@ export function readProvenanceTag(line: string): {
     return { provenance: null, line };
   }
   const candidate = line.slice(PROVENANCE_PREFIX.length, end);
-  const provenance = LOG_PROVENANCE_CLASSES.includes(
-    candidate as LogProvenance,
-  )
+  const provenance = LOG_PROVENANCE_CLASSES.includes(candidate as LogProvenance)
     ? (candidate as LogProvenance)
     : null;
   return { provenance, line: line.slice(end + 1) };

package/dist/bundling-sources/shared_libs/play-runtime/protocol.ts

@@ -17,6 +17,7 @@ import type { PlayRunFailureDetails } from './run-failure';
 import type { ToolExecutionErrorSchemaVersion } from '../plays/tool-execution-error';
 import type { ToolResponseContract } from '../plays/tool-response-contract';
 import type { FixtureBehavior } from './fixture-behavior';
+import type { CtxFetchHttpFailureDiagnostic } from './log-provenance';
 
 export type PlayRunnerRateStateBackendConfig =
   | {
@@ -307,6 +308,8 @@ export type PlayRunnerResult =
       status: 'completed';
       output: unknown;
       outputWarnings?: PlayRunOutputWarning[];
+      /** Customer-safe runtime observations that must survive bounded log tails. */
+      runtimeDiagnostics?: CtxFetchHttpFailureDiagnostic[];
       outputRowCount?: number;
       logs: string[];
       stats: Record<string, unknown>;

package/dist/cli/index.js

@@ -1214,7 +1214,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.65",
+  version: "0.3.66",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1
@@ -16758,9 +16758,7 @@ function readProvenanceTag(line) {
     return { provenance: null, line };
   }
   const candidate = line.slice(PROVENANCE_PREFIX.length, end);
-  const provenance = LOG_PROVENANCE_CLASSES.includes(
-    candidate
-  ) ? candidate : null;
+  const provenance = LOG_PROVENANCE_CLASSES.includes(candidate) ? candidate : null;
   return { provenance, line: line.slice(end + 1) };
 }
 function classifyLegacyLogLine(line) {
@@ -17094,12 +17092,16 @@ var PLAY_RUN_RESERVED_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--watch",
   "--no-wait",
   "--logs",
+  "--debug",
   "--full",
   "--force",
   "--force-tool-refresh",
   "--open",
   "--debug-map-latency"
 ]);
+function isBarePlayRunDebugFlag(args, index) {
+  return args[index] === "--debug" && (args[index + 1] === void 0 || args[index + 1].startsWith("--"));
+}
 async function pathExistsIncludingSymlink(path) {
   try {
     await (0, import_promises6.lstat)(path);
@@ -21057,12 +21059,13 @@ function parsePlayRunOptions(args) {
   const watch = !args.includes("--no-wait");
   let jsonOutput = watch ? args.includes("--json") : argsWantJson(args);
   const fullJson = args.includes("--full");
-  const emitLogs = !jsonOutput || args.includes("--logs");
+  const explicitDebugLogs = args.includes("--logs") || args.some((_, index) => isBarePlayRunDebugFlag(args, index));
+  const emitLogs = !jsonOutput || explicitDebugLogs;
   const force = args.includes("--force");
   const forceToolRefresh = args.includes("--force-tool-refresh");
   const open2 = args.includes("--open");
   const debugMapLatency = args.includes("--debug-map-latency");
-  const verboseLogs = args.includes("--logs") || debugMapLatency;
+  const verboseLogs = explicitDebugLogs || debugMapLatency;
   let waitTimeoutMs = null;
   let maxConcurrentExternalCalls = null;
   let maxConcurrentRows = null;
@@ -21193,6 +21196,20 @@ function parsePlayRunOptions(args) {
       waitTimeoutMs = parsePositiveInteger3(args[++index], arg);
       continue;
     }
+    if (arg === "--debug" && args[index + 1] && !args[index + 1].startsWith("--")) {
+      input2 ??= {};
+      setDottedInputValue(input2, "debug", parseInputFlagValue(args[++index]));
+      continue;
+    }
+    if (arg.startsWith("--debug=")) {
+      input2 ??= {};
+      setDottedInputValue(
+        input2,
+        "debug",
+        parseInputFlagValue(arg.slice("--debug=".length))
+      );
+      continue;
+    }
     if (PLAY_RUN_RESERVED_BOOLEAN_FLAGS.has(arg)) {
       if (arg === "--watch") {
         continue;
@@ -22451,7 +22468,7 @@ async function handlePlayRun(args, hooks) {
 function parseRunIdPositional(args, usage) {
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
-    if (arg === "--json" || arg === "--full" || arg === "--input" || arg === "--logs" || arg === "--compact" || arg === "--log-failed" || arg === "--failed" || arg === "--limit") {
+    if (arg === "--json" || arg === "--full" || arg === "--input" || arg === "--logs" || arg === "--debug" || arg === "--compact" || arg === "--log-failed" || arg === "--failed" || arg === "--limit") {
       if (arg === "--limit" && args[index + 1]) {
         index += 1;
       }
@@ -22599,7 +22616,7 @@ async function handleRunsList(args) {
   return 0;
 }
 async function handleRunTail(args) {
-  const usage = "Usage: deepline runs tail <run-id> [--json | --jsonl] [--compact]";
+  const usage = "Usage: deepline runs tail <run-id> [--json | --jsonl] [--compact] [--debug]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -22615,7 +22632,7 @@ async function handleRunTail(args) {
       );
       return 1;
     }
-    if (arg.startsWith("--") && arg !== "--json" && arg !== "--jsonl" && arg !== "--compact") {
+    if (arg.startsWith("--") && arg !== "--json" && arg !== "--jsonl" && arg !== "--compact" && arg !== "--logs" && arg !== "--debug") {
       console.error(`${arg} is not supported by deepline runs tail.`);
       return 1;
     }
@@ -22624,6 +22641,13 @@ async function handleRunTail(args) {
     console.error("--json and --jsonl cannot be used together.");
     return 1;
   }
+  const debug = args.includes("--logs") || args.includes("--debug");
+  if (args.includes("--jsonl") && debug) {
+    console.error(
+      "--debug is redundant with --jsonl: JSON Lines already includes every canonical live event."
+    );
+    return 1;
+  }
   const client2 = new DeeplineClient();
   const jsonLines = args.includes("--jsonl");
   const jsonOutput = !jsonLines && argsWantJson(args);
@@ -22633,7 +22657,8 @@ async function handleRunTail(args) {
     emittedRunnerStarted: false,
     lastProgressSignature: null,
     lastProgressHeartbeatAt: 0,
-    lastStatusHeartbeatAt: 0
+    lastStatusHeartbeatAt: 0,
+    verbose: debug
   };
   const status = await client2.runs.tail(runId, {
     onEvent: jsonLines ? (event) => {
@@ -22645,7 +22670,20 @@ async function handleRunTail(args) {
         })}
 `
       );
-    } : compact && !jsonOutput ? (event) => {
+    } : compact || debug ? (event) => {
+      if (debug) {
+        for (const line of getLogLinesFromLiveEvent(event)) {
+          const formatted = formatPlayLogLine(
+            line,
+            void 0,
+            compactState
+          );
+          if (formatted) process.stderr.write(`${formatted}
+`);
+          compactState.lastLogIndex += 1;
+        }
+      }
+      if (!compact || jsonOutput) return;
       const transition = getStepTransitionLineFromLiveEvent(
         event,
         compactState
@@ -22668,7 +22706,7 @@ async function handleRunTail(args) {
       }
     } : void 0,
     // Human mode only: in --json mode emit nothing non-protocol.
-    onReconnect: jsonOutput ? void 0 : ({ reason }) => {
+    onReconnect: jsonOutput && !debug ? void 0 : ({ reason }) => {
       process.stderr.write(
         `[runs tail] stream ended without a terminal status; reconnecting to run ${runId} (${reason})
 `
@@ -22684,7 +22722,7 @@ async function handleRunTail(args) {
   return status.status === "failed" ? 1 : 0;
 }
 async function handleRunLogs(args) {
-  const usage = "Usage: deepline runs logs <run-id> [--limit 200] [--failed] [--out run.log] [--json]";
+  const usage = "Usage: deepline runs logs <run-id> [--limit 200] [--failed] [--out run.log] [--json] [--debug]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -22697,12 +22735,20 @@ async function handleRunLogs(args) {
   const failed = args.includes("--failed");
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
+    if (arg === "--debug" || arg === "--logs" || arg === "--json" || arg === "--failed") {
+      continue;
+    }
     if (arg === "--limit" && args[index + 1]) {
       limit = parsePositiveInteger3(args[++index], "--limit");
       continue;
     }
     if (arg === "--out" && args[index + 1]) {
       outPath = (0, import_node_path14.resolve)(args[++index]);
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      console.error(`${arg} is not supported by deepline runs logs.`);
+      return 1;
     }
   }
   if (failed && outPath) {
@@ -24175,9 +24221,9 @@ Examples:
   ).option("--watch", "Compatibility alias; run waits by default").option("--wait", "Compatibility alias; run waits by default").option("--no-wait", "Start the run and return immediately").option(
     "--run-id-file <path>",
     "Atomically write the accepted run id to a new JSON file"
-  ).option(
-    "--logs",
-    "When output is non-interactive, stream play logs to stderr while waiting"
+  ).option("--logs", "Compatibility alias for --debug").option(
+    "--debug [value]",
+    "Stream complete customer-safe runtime logs when passed without a value; otherwise pass input.debug"
   ).option("--tail-timeout-ms <ms>", "Timeout while watching the run stream").option("--force", "Start a fresh run graph").option(
     "--force-tool-refresh",
     "Refresh completed tool receipts; may repeat billed provider calls"
@@ -24226,6 +24272,7 @@ Pass-through input flags:
       ...options.runIdFile ? ["--run-id-file", options.runIdFile] : [],
       ...options.watch || options.wait ? ["--watch"] : [],
       ...options.logs ? ["--logs"] : [],
+      ...options.debug === true ? ["--debug"] : typeof options.debug === "string" ? ["--debug", options.debug] : [],
       ...options.tailTimeoutMs ? ["--tail-timeout-ms", options.tailTimeoutMs] : [],
       ...options.force ? ["--force"] : [],
       ...options.forceToolRefresh ? ["--force-tool-refresh"] : [],
@@ -24643,11 +24690,13 @@ Notes:
   logs for persisted log history. In human output, --compact prints deduplicated
   step transitions and progress instead of the full event stream. --json emits
   one terminal package. --jsonl emits canonical live events as JSON Lines and
-  ends with the same compact package shape as runs get --json.
+  ends with the same compact package shape as runs get --json. Use --debug
+  (or legacy --logs) to also print customer-safe runtime log lines to stderr.
 
 Examples:
   deepline runs tail play/my-play/run/20260501t000000-000
   deepline runs tail play/my-play/run/20260501t000000-000 --compact
+  deepline runs tail play/my-play/run/20260501t000000-000 --debug
   deepline runs tail play/my-play/run/20260501t000000-000 --jsonl
 `
   ).option("--json", "Emit one terminal JSON package after the run completes").option(
@@ -24656,12 +24705,17 @@ Examples:
   ).option(
     "--compact",
     "Show deduplicated human step transitions and progress"
+  ).option("--logs", "Compatibility alias for --debug").option(
+    "--debug",
+    "Print customer-safe runtime log lines to stderr while tailing"
   ).action(async (runId, options) => {
     process.exitCode = await handleRunTail([
       runId,
       ...options.json ? ["--json"] : [],
       ...options.jsonl ? ["--jsonl"] : [],
-      ...options.compact ? ["--compact"] : []
+      ...options.compact ? ["--compact"] : [],
+      ...options.logs ? ["--logs"] : [],
+      ...options.debug ? ["--debug"] : []
     ]);
   });
   runs.command("logs <runId>").description("Fetch persisted logs for a play run.").addHelpText(
@@ -24669,24 +24723,31 @@ Examples:
     `
 Notes:
   Prints a bounded recent log preview by default. Use --out to write the full
-  persisted log stream to a local file.
+  persisted log stream to a local file. --debug (or legacy --logs) is accepted
+  for script parity; this command already returns the unfiltered durable stream.
 
 Examples:
   deepline runs logs play/my-play/run/20260501t000000-000
   deepline runs logs play/my-play/run/20260501t000000-000 --limit 500
   deepline runs logs play/my-play/run/20260501t000000-000 --failed --json
+  deepline runs logs play/my-play/run/20260501t000000-000 --debug
   deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --json
 `
   ).option(
     "--limit <count>",
     "Maximum recent log lines to print without --out",
     "200"
-  ).option("--out <path>", "Write the full persisted log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  ).option("--out <path>", "Write the full persisted log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option("--logs", "Compatibility alias for --debug").option(
+    "--debug",
+    "Explicitly request the same persisted log view (no provenance filtering)"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunLogs([
       runId,
       ...options.limit ? ["--limit", options.limit] : [],
       ...options.out ? ["--out", options.out] : [],
       ...options.failed ? ["--failed"] : [],
+      ...options.logs ? ["--logs"] : [],
+      ...options.debug ? ["--debug"] : [],
       ...options.json ? ["--json"] : []
     ]);
   });

package/dist/cli/index.mjs

@@ -1199,7 +1199,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.65",
+  version: "0.3.66",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1
@@ -16820,9 +16820,7 @@ function readProvenanceTag(line) {
     return { provenance: null, line };
   }
   const candidate = line.slice(PROVENANCE_PREFIX.length, end);
-  const provenance = LOG_PROVENANCE_CLASSES.includes(
-    candidate
-  ) ? candidate : null;
+  const provenance = LOG_PROVENANCE_CLASSES.includes(candidate) ? candidate : null;
   return { provenance, line: line.slice(end + 1) };
 }
 function classifyLegacyLogLine(line) {
@@ -17156,12 +17154,16 @@ var PLAY_RUN_RESERVED_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--watch",
   "--no-wait",
   "--logs",
+  "--debug",
   "--full",
   "--force",
   "--force-tool-refresh",
   "--open",
   "--debug-map-latency"
 ]);
+function isBarePlayRunDebugFlag(args, index) {
+  return args[index] === "--debug" && (args[index + 1] === void 0 || args[index + 1].startsWith("--"));
+}
 async function pathExistsIncludingSymlink(path) {
   try {
     await lstat(path);
@@ -21119,12 +21121,13 @@ function parsePlayRunOptions(args) {
   const watch = !args.includes("--no-wait");
   let jsonOutput = watch ? args.includes("--json") : argsWantJson(args);
   const fullJson = args.includes("--full");
-  const emitLogs = !jsonOutput || args.includes("--logs");
+  const explicitDebugLogs = args.includes("--logs") || args.some((_, index) => isBarePlayRunDebugFlag(args, index));
+  const emitLogs = !jsonOutput || explicitDebugLogs;
   const force = args.includes("--force");
   const forceToolRefresh = args.includes("--force-tool-refresh");
   const open2 = args.includes("--open");
   const debugMapLatency = args.includes("--debug-map-latency");
-  const verboseLogs = args.includes("--logs") || debugMapLatency;
+  const verboseLogs = explicitDebugLogs || debugMapLatency;
   let waitTimeoutMs = null;
   let maxConcurrentExternalCalls = null;
   let maxConcurrentRows = null;
@@ -21255,6 +21258,20 @@ function parsePlayRunOptions(args) {
       waitTimeoutMs = parsePositiveInteger3(args[++index], arg);
       continue;
     }
+    if (arg === "--debug" && args[index + 1] && !args[index + 1].startsWith("--")) {
+      input2 ??= {};
+      setDottedInputValue(input2, "debug", parseInputFlagValue(args[++index]));
+      continue;
+    }
+    if (arg.startsWith("--debug=")) {
+      input2 ??= {};
+      setDottedInputValue(
+        input2,
+        "debug",
+        parseInputFlagValue(arg.slice("--debug=".length))
+      );
+      continue;
+    }
     if (PLAY_RUN_RESERVED_BOOLEAN_FLAGS.has(arg)) {
       if (arg === "--watch") {
         continue;
@@ -22513,7 +22530,7 @@ async function handlePlayRun(args, hooks) {
 function parseRunIdPositional(args, usage) {
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
-    if (arg === "--json" || arg === "--full" || arg === "--input" || arg === "--logs" || arg === "--compact" || arg === "--log-failed" || arg === "--failed" || arg === "--limit") {
+    if (arg === "--json" || arg === "--full" || arg === "--input" || arg === "--logs" || arg === "--debug" || arg === "--compact" || arg === "--log-failed" || arg === "--failed" || arg === "--limit") {
       if (arg === "--limit" && args[index + 1]) {
         index += 1;
       }
@@ -22661,7 +22678,7 @@ async function handleRunsList(args) {
   return 0;
 }
 async function handleRunTail(args) {
-  const usage = "Usage: deepline runs tail <run-id> [--json | --jsonl] [--compact]";
+  const usage = "Usage: deepline runs tail <run-id> [--json | --jsonl] [--compact] [--debug]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -22677,7 +22694,7 @@ async function handleRunTail(args) {
       );
       return 1;
     }
-    if (arg.startsWith("--") && arg !== "--json" && arg !== "--jsonl" && arg !== "--compact") {
+    if (arg.startsWith("--") && arg !== "--json" && arg !== "--jsonl" && arg !== "--compact" && arg !== "--logs" && arg !== "--debug") {
       console.error(`${arg} is not supported by deepline runs tail.`);
       return 1;
     }
@@ -22686,6 +22703,13 @@ async function handleRunTail(args) {
     console.error("--json and --jsonl cannot be used together.");
     return 1;
   }
+  const debug = args.includes("--logs") || args.includes("--debug");
+  if (args.includes("--jsonl") && debug) {
+    console.error(
+      "--debug is redundant with --jsonl: JSON Lines already includes every canonical live event."
+    );
+    return 1;
+  }
   const client2 = new DeeplineClient();
   const jsonLines = args.includes("--jsonl");
   const jsonOutput = !jsonLines && argsWantJson(args);
@@ -22695,7 +22719,8 @@ async function handleRunTail(args) {
     emittedRunnerStarted: false,
     lastProgressSignature: null,
     lastProgressHeartbeatAt: 0,
-    lastStatusHeartbeatAt: 0
+    lastStatusHeartbeatAt: 0,
+    verbose: debug
   };
   const status = await client2.runs.tail(runId, {
     onEvent: jsonLines ? (event) => {
@@ -22707,7 +22732,20 @@ async function handleRunTail(args) {
         })}
 `
       );
-    } : compact && !jsonOutput ? (event) => {
+    } : compact || debug ? (event) => {
+      if (debug) {
+        for (const line of getLogLinesFromLiveEvent(event)) {
+          const formatted = formatPlayLogLine(
+            line,
+            void 0,
+            compactState
+          );
+          if (formatted) process.stderr.write(`${formatted}
+`);
+          compactState.lastLogIndex += 1;
+        }
+      }
+      if (!compact || jsonOutput) return;
       const transition = getStepTransitionLineFromLiveEvent(
         event,
         compactState
@@ -22730,7 +22768,7 @@ async function handleRunTail(args) {
       }
     } : void 0,
     // Human mode only: in --json mode emit nothing non-protocol.
-    onReconnect: jsonOutput ? void 0 : ({ reason }) => {
+    onReconnect: jsonOutput && !debug ? void 0 : ({ reason }) => {
       process.stderr.write(
         `[runs tail] stream ended without a terminal status; reconnecting to run ${runId} (${reason})
 `
@@ -22746,7 +22784,7 @@ async function handleRunTail(args) {
   return status.status === "failed" ? 1 : 0;
 }
 async function handleRunLogs(args) {
-  const usage = "Usage: deepline runs logs <run-id> [--limit 200] [--failed] [--out run.log] [--json]";
+  const usage = "Usage: deepline runs logs <run-id> [--limit 200] [--failed] [--out run.log] [--json] [--debug]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -22759,12 +22797,20 @@ async function handleRunLogs(args) {
   const failed = args.includes("--failed");
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
+    if (arg === "--debug" || arg === "--logs" || arg === "--json" || arg === "--failed") {
+      continue;
+    }
     if (arg === "--limit" && args[index + 1]) {
       limit = parsePositiveInteger3(args[++index], "--limit");
       continue;
     }
     if (arg === "--out" && args[index + 1]) {
       outPath = resolve11(args[++index]);
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      console.error(`${arg} is not supported by deepline runs logs.`);
+      return 1;
     }
   }
   if (failed && outPath) {
@@ -24237,9 +24283,9 @@ Examples:
   ).option("--watch", "Compatibility alias; run waits by default").option("--wait", "Compatibility alias; run waits by default").option("--no-wait", "Start the run and return immediately").option(
     "--run-id-file <path>",
     "Atomically write the accepted run id to a new JSON file"
-  ).option(
-    "--logs",
-    "When output is non-interactive, stream play logs to stderr while waiting"
+  ).option("--logs", "Compatibility alias for --debug").option(
+    "--debug [value]",
+    "Stream complete customer-safe runtime logs when passed without a value; otherwise pass input.debug"
   ).option("--tail-timeout-ms <ms>", "Timeout while watching the run stream").option("--force", "Start a fresh run graph").option(
     "--force-tool-refresh",
     "Refresh completed tool receipts; may repeat billed provider calls"
@@ -24288,6 +24334,7 @@ Pass-through input flags:
       ...options.runIdFile ? ["--run-id-file", options.runIdFile] : [],
       ...options.watch || options.wait ? ["--watch"] : [],
       ...options.logs ? ["--logs"] : [],
+      ...options.debug === true ? ["--debug"] : typeof options.debug === "string" ? ["--debug", options.debug] : [],
       ...options.tailTimeoutMs ? ["--tail-timeout-ms", options.tailTimeoutMs] : [],
       ...options.force ? ["--force"] : [],
       ...options.forceToolRefresh ? ["--force-tool-refresh"] : [],
@@ -24705,11 +24752,13 @@ Notes:
   logs for persisted log history. In human output, --compact prints deduplicated
   step transitions and progress instead of the full event stream. --json emits
   one terminal package. --jsonl emits canonical live events as JSON Lines and
-  ends with the same compact package shape as runs get --json.
+  ends with the same compact package shape as runs get --json. Use --debug
+  (or legacy --logs) to also print customer-safe runtime log lines to stderr.
 
 Examples:
   deepline runs tail play/my-play/run/20260501t000000-000
   deepline runs tail play/my-play/run/20260501t000000-000 --compact
+  deepline runs tail play/my-play/run/20260501t000000-000 --debug
   deepline runs tail play/my-play/run/20260501t000000-000 --jsonl
 `
   ).option("--json", "Emit one terminal JSON package after the run completes").option(
@@ -24718,12 +24767,17 @@ Examples:
   ).option(
     "--compact",
     "Show deduplicated human step transitions and progress"
+  ).option("--logs", "Compatibility alias for --debug").option(
+    "--debug",
+    "Print customer-safe runtime log lines to stderr while tailing"
   ).action(async (runId, options) => {
     process.exitCode = await handleRunTail([
       runId,
       ...options.json ? ["--json"] : [],
       ...options.jsonl ? ["--jsonl"] : [],
-      ...options.compact ? ["--compact"] : []
+      ...options.compact ? ["--compact"] : [],
+      ...options.logs ? ["--logs"] : [],
+      ...options.debug ? ["--debug"] : []
     ]);
   });
   runs.command("logs <runId>").description("Fetch persisted logs for a play run.").addHelpText(
@@ -24731,24 +24785,31 @@ Examples:
     `
 Notes:
   Prints a bounded recent log preview by default. Use --out to write the full
-  persisted log stream to a local file.
+  persisted log stream to a local file. --debug (or legacy --logs) is accepted
+  for script parity; this command already returns the unfiltered durable stream.
 
 Examples:
   deepline runs logs play/my-play/run/20260501t000000-000
   deepline runs logs play/my-play/run/20260501t000000-000 --limit 500
   deepline runs logs play/my-play/run/20260501t000000-000 --failed --json
+  deepline runs logs play/my-play/run/20260501t000000-000 --debug
   deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --json
 `
   ).option(
     "--limit <count>",
     "Maximum recent log lines to print without --out",
     "200"
-  ).option("--out <path>", "Write the full persisted log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  ).option("--out <path>", "Write the full persisted log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option("--logs", "Compatibility alias for --debug").option(
+    "--debug",
+    "Explicitly request the same persisted log view (no provenance filtering)"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunLogs([
       runId,
       ...options.limit ? ["--limit", options.limit] : [],
       ...options.out ? ["--out", options.out] : [],
       ...options.failed ? ["--failed"] : [],
+      ...options.logs ? ["--logs"] : [],
+      ...options.debug ? ["--debug"] : [],
       ...options.json ? ["--json"] : []
     ]);
   });

package/dist/index.js

@@ -832,7 +832,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.65",
+  version: "0.3.66",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/index.mjs

@@ -744,7 +744,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.65",
+  version: "0.3.66",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.65",
+  "version": "0.3.66",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",