deepline 0.1.19 → 0.1.21

package/dist/cli/index.mjs

@@ -243,7 +243,7 @@ function saveProjectDeeplineEnvValues(baseUrl, values, startDir = projectEnvStar
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.19";
+var SDK_VERSION = "0.1.21";
 var SDK_API_CONTRACT = "2026-05-runs-v2";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
@@ -326,7 +326,7 @@ var HttpClient = class {
           const response = await fetch(candidateUrl, {
             method,
             headers,
-            body: options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
+            body: options?.formData !== void 0 ? options.formData : options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
             signal: controller.signal
           });
           clearTimeout(timeoutId);
@@ -350,7 +350,8 @@ var HttpClient = class {
             parsed = body;
           }
           if (!response.ok) {
-            const msg = typeof parsed === "object" && parsed && "error" in parsed ? String(parsed.error) : `HTTP ${response.status}`;
+            const errorValue = typeof parsed === "object" && parsed && "error" in parsed ? parsed.error : void 0;
+            const msg = typeof errorValue === "string" ? errorValue : errorValue && typeof errorValue === "object" && "message" in errorValue && typeof errorValue.message === "string" ? errorValue.message : typeof parsed === "object" && parsed && "message" in parsed && typeof parsed.message === "string" ? parsed.message : `HTTP ${response.status}`;
             throw new DeeplineError(msg, response.status, "API_ERROR", {
               response: parsed
             });
@@ -444,6 +445,13 @@ var HttpClient = class {
       headers
     });
   }
+  async postFormData(path, formData, headers) {
+    return this.request(path, {
+      method: "POST",
+      formData,
+      headers
+    });
+  }
   /**
    * Send a DELETE request.
    *
@@ -552,6 +560,14 @@ function mapLegacyTemporalStatus(status) {
       return "running";
   }
 }
+function decodeBase64Bytes(value) {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
 var DeeplineClient = class {
   http;
   config;
@@ -1003,9 +1019,34 @@ var DeeplineClient = class {
    * ```
    */
   async stagePlayFiles(files) {
-    const response = await this.http.post(
+    const formData = new FormData();
+    formData.set(
+      "metadata",
+      JSON.stringify({
+        files: files.map((file, index) => ({
+          index,
+          logicalPath: file.logicalPath,
+          contentHash: file.contentHash,
+          contentType: file.contentType,
+          bytes: file.bytes
+        }))
+      })
+    );
+    for (const [index, file] of files.entries()) {
+      const bytes = decodeBase64Bytes(file.contentBase64);
+      const body = bytes.buffer.slice(
+        bytes.byteOffset,
+        bytes.byteOffset + bytes.byteLength
+      );
+      formData.set(
+        `file:${index}`,
+        new Blob([body], { type: file.contentType }),
+        file.logicalPath
+      );
+    }
+    const response = await this.http.postFormData(
       "/api/v2/plays/files/stage",
-      { files }
+      formData
     );
     return response.files;
   }
@@ -1034,9 +1075,14 @@ var DeeplineClient = class {
    * console.log(`Logs: ${status.progress?.logs.length ?? 0} lines`);
    * ```
    */
-  async getPlayStatus(workflowId) {
+  async getPlayStatus(workflowId, options) {
+    const params = new URLSearchParams();
+    if (options?.billing === false) {
+      params.set("billing", "false");
+    }
+    const query = params.size > 0 ? `?${params.toString()}` : "";
     const response = await this.http.get(
-      `/api/v2/plays/run/${encodeURIComponent(workflowId)}`
+      `/api/v2/plays/run/${encodeURIComponent(workflowId)}${query}`
     );
     return normalizePlayStatus(response);
   }
@@ -4342,7 +4388,77 @@ function createCliProgress(enabled) {
   return progress;
 }
 
+// src/cli/trace.ts
+var cliTraceStartedAt = Date.now();
+function isTruthyEnv(value) {
+  return value === "1" || value === "true" || value === "yes";
+}
+function isCliTraceEnabled() {
+  return isTruthyEnv(process.env.DEEPLINE_CLI_TRACE);
+}
+function recordCliTrace(event) {
+  if (!isCliTraceEnabled()) {
+    return;
+  }
+  const now = Date.now();
+  const payload = {
+    ts: now,
+    source: "cli",
+    sinceStartMs: now - cliTraceStartedAt,
+    ...event
+  };
+  process.stderr.write(`[cli-trace] ${JSON.stringify(payload)}
+`);
+}
+async function traceCliSpan(phase, fields, run) {
+  if (!isCliTraceEnabled()) {
+    return run();
+  }
+  const startedAt = Date.now();
+  try {
+    const result = await run();
+    recordCliTrace({
+      phase,
+      ms: Date.now() - startedAt,
+      ok: true,
+      ...fields
+    });
+    return result;
+  } catch (error) {
+    recordCliTrace({
+      phase,
+      ms: Date.now() - startedAt,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+      ...fields
+    });
+    throw error;
+  }
+}
+
 // src/cli/commands/play.ts
+function traceCliSync(phase, fields, run) {
+  const startedAt = Date.now();
+  try {
+    const result = run();
+    recordCliTrace({
+      phase,
+      ms: Date.now() - startedAt,
+      ok: true,
+      ...fields
+    });
+    return result;
+  } catch (error) {
+    recordCliTrace({
+      phase,
+      ms: Date.now() - startedAt,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+      ...fields
+    });
+    throw error;
+  }
+}
 function parseReferencedPlayTarget(target) {
   const trimmed = target.trim();
   const slashIndex = trimmed.indexOf("/");
@@ -4581,6 +4697,23 @@ function isLocalFilePathValue(value) {
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value.trim())) return false;
   return existsSync4(resolve7(value));
 }
+function inputContainsLocalFilePath(value) {
+  if (isLocalFilePathValue(value)) {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.some((entry) => inputContainsLocalFilePath(entry));
+  }
+  if (value && typeof value === "object") {
+    return Object.values(value).some(
+      (entry) => inputContainsLocalFilePath(entry)
+    );
+  }
+  return false;
+}
+function namedRunNeedsPlayDefinition(input) {
+  return input.revisionSelector === "latest" || getDottedInputValue(input.runtimeInput, "csv") != null || inputContainsLocalFilePath(input.runtimeInput);
+}
 async function stageFileInputArgs(input) {
   const uniqueBindings = [
     ...new Map(input.bindings.map((binding) => [binding.inputPath, binding])).values()
@@ -4893,6 +5026,8 @@ async function startAndWaitForPlayCompletionByStream(input) {
   let timedOut = false;
   let emittedDashboardUrl = false;
   let lastKnownWorkflowId = "";
+  let eventCount = 0;
+  let firstRunIdMs = null;
   let lastPhase = null;
   const timeout = input.waitTimeoutMs === null ? null : setTimeout(
     () => {
@@ -4905,9 +5040,11 @@ async function startAndWaitForPlayCompletionByStream(input) {
     for await (const event of input.client.startPlayRunStream(input.request, {
       signal: controller.signal
     })) {
+      eventCount += 1;
       const eventRunId = getEventPayload(event).runId;
       if (typeof eventRunId === "string" && eventRunId && eventRunId !== "pending") {
         lastKnownWorkflowId = eventRunId;
+        firstRunIdMs ??= Date.now() - startedAt;
       }
       const workflowId = lastKnownWorkflowId || "pending";
       if (workflowId !== "pending" && !emittedDashboardUrl) {
@@ -4945,6 +5082,16 @@ async function startAndWaitForPlayCompletionByStream(input) {
       });
       const finalStatus = getFinalStatusFromLiveEvent(event);
       if (finalStatus) {
+        recordCliTrace({
+          phase: "cli.play_start_stream_terminal",
+          ms: Date.now() - startedAt,
+          ok: true,
+          playName: input.playName,
+          workflowId: finalStatus.runId || lastKnownWorkflowId || null,
+          eventCount,
+          firstRunIdMs,
+          lastPhase
+        });
         return finalStatus;
       }
     }
@@ -4968,6 +5115,17 @@ async function startAndWaitForPlayCompletionByStream(input) {
 `
         );
       }
+      recordCliTrace({
+        phase: "cli.play_start_stream_fallback",
+        ms: Date.now() - startedAt,
+        ok: false,
+        playName: input.playName,
+        workflowId: lastKnownWorkflowId,
+        eventCount,
+        firstRunIdMs,
+        lastPhase,
+        reason
+      });
       return waitForPlayCompletionByPolling({
         client: input.client,
         workflowId: lastKnownWorkflowId,
@@ -4992,6 +5150,17 @@ async function startAndWaitForPlayCompletionByStream(input) {
         `[play watch] start stream ended after run ${lastKnownWorkflowId}; falling back to polling`
       );
     }
+    recordCliTrace({
+      phase: "cli.play_start_stream_fallback",
+      ms: Date.now() - startedAt,
+      ok: false,
+      playName: input.playName,
+      workflowId: lastKnownWorkflowId,
+      eventCount,
+      firstRunIdMs,
+      lastPhase,
+      reason: "stream ended before terminal event"
+    });
     return waitForPlayCompletionByPolling({
       client: input.client,
       workflowId: lastKnownWorkflowId,
@@ -5066,10 +5235,11 @@ async function waitForPlayCompletionByPolling(input) {
       progress: input.progress
     });
     if (TERMINAL_PLAY_STATUSES2.has(status.status)) {
-      return status.result !== void 0 ? status : await input.client.getPlayStatus(input.workflowId);
+      return status.result !== void 0 ? status : await input.client.getPlayStatus(input.workflowId, { billing: false });
     }
     const authoritativeStatus = await input.client.getPlayStatus(
-      input.workflowId
+      input.workflowId,
+      { billing: false }
     );
     if (TERMINAL_PLAY_STATUSES2.has(authoritativeStatus.status)) {
       return authoritativeStatus;
@@ -5187,14 +5357,20 @@ function formatReturnValue(result) {
   }
   return lines;
 }
-function buildOutputSummary(rowsInfo, exportedPath) {
+function buildOutputSummary(rowsInfo, runId, exportedPath) {
   if (!rowsInfo) {
     return exportedPath ? { csv_path: exportedPath } : null;
   }
+  const isPartial = !rowsInfo.complete;
   return {
     kind: "rows",
     rowCount: rowsInfo.totalRows,
     previewRowCount: rowsInfo.rows.length,
+    ...isPartial ? {
+      isPartial: true,
+      previewCount: rowsInfo.rows.length,
+      totalCount: rowsInfo.totalRows
+    } : { isPartial: false },
     complete: rowsInfo.complete,
     columns: rowsInfo.columns,
     source: rowsInfo.source,
@@ -5205,16 +5381,27 @@ function buildRunWarnings(status, rowsInfo) {
   if (status.status === "completed" && rowsInfo?.totalRows === 0) {
     return ["Run completed with 0 output rows."];
   }
+  if (rowsInfo && !rowsInfo.complete) {
+    return [
+      `Run output is partial: showing ${rowsInfo.rows.length} preview row(s) of ${rowsInfo.totalRows}.`
+    ];
+  }
   return [];
 }
-function buildRunNextCommands(runId) {
-  return {
+function buildRunNextCommands(runId, rowsInfo) {
+  const commands = {
     get: `deepline runs get ${runId} --json`,
     tail: `deepline runs tail ${runId} --json`,
     stop: `deepline runs stop ${runId} --reason "stale lock" --json`,
-    logs: `deepline runs logs ${runId} --out run.log --json`,
-    exportCsv: `deepline runs export ${runId} --out output.csv`
+    logs: `deepline runs logs ${runId} --out run.log --json`
   };
+  if (!rowsInfo || rowsInfo.complete) {
+    commands.exportCsv = buildRunExportCommand(runId);
+  }
+  return commands;
+}
+function buildRunExportCommand(runId) {
+  return `deepline runs export ${runId} --out output.csv`;
 }
 var RUN_LOG_PREVIEW_LIMIT = 20;
 function getRecordField(value, key) {
@@ -5262,10 +5449,11 @@ function normalizeProgressForEnvelope(status, rowsInfo) {
     wait: status.wait ?? null
   };
 }
-function normalizeOutputsForEnvelope(rowsInfo, exportedPath) {
+function normalizeOutputsForEnvelope(rowsInfo, runId, exportedPath) {
   if (!rowsInfo) {
     return exportedPath ? [{ name: "output", kind: "file", path: exportedPath }] : [];
   }
+  const isPartial = !rowsInfo.complete;
   return [
     {
       name: "rows",
@@ -5275,6 +5463,11 @@ function normalizeOutputsForEnvelope(rowsInfo, exportedPath) {
       preview: rowsInfo.rows.slice(0, 5),
       previewRowCount: Math.min(rowsInfo.rows.length, 5),
       previewLimit: 5,
+      ...isPartial ? {
+        isPartial: true,
+        previewCount: rowsInfo.rows.length,
+        totalCount: rowsInfo.totalRows
+      } : { isPartial: false },
       complete: rowsInfo.complete,
       source: rowsInfo.source,
       ...exportedPath ? { csv_path: exportedPath } : {}
@@ -5366,19 +5559,23 @@ function compactPlayStatus(status, options) {
     status: status.status,
     run: normalizeRunStatusForEnvelope(status),
     progress: normalizeProgressForEnvelope(status, rowsInfo),
-    outputs: normalizeOutputsForEnvelope(rowsInfo, options?.exportedPath),
+    outputs: normalizeOutputsForEnvelope(
+      rowsInfo,
+      status.runId,
+      options?.exportedPath
+    ),
     steps: normalizeStepsForEnvelope(status),
     errors: normalizeErrorsForEnvelope(status, error),
     logs: normalizeLogsForEnvelope(status),
     ...error ? { error } : {},
     ...warnings.length > 0 ? { warnings } : {},
-    output: buildOutputSummary(rowsInfo, options?.exportedPath) ?? result ?? null,
+    output: buildOutputSummary(rowsInfo, status.runId, options?.exportedPath) ?? result ?? null,
     ...result !== void 0 ? { result } : {},
     ...status.resultView ? { resultView: status.resultView } : {},
     ...datasetStats ? { dataset_stats: datasetStats } : {},
     ...rowsInfo ? { previewRows: rowsInfo.rows.slice(0, 5) } : {},
     ...billing ? { billing } : {},
-    next: buildRunNextCommands(status.runId)
+    next: buildRunNextCommands(status.runId, rowsInfo)
   };
 }
 function enrichPlayStatusWithDatasetStats(status) {
@@ -5438,13 +5635,22 @@ function writePlayResult(status, jsonOutput, options) {
     rowsInfo.columns,
     extractDatasetExecutionStats(status)
   ) : null;
-  const outputSummary = buildOutputSummary(rowsInfo, options?.exportedPath);
+  const outputSummary = buildOutputSummary(
+    rowsInfo,
+    runId,
+    options?.exportedPath
+  );
   if (outputSummary) {
     const columns = Array.isArray(outputSummary.columns) ? outputSummary.columns.length : 0;
     const path = typeof outputSummary.csv_path === "string" ? `  file=${outputSummary.csv_path}` : "";
     lines.push(
       `  output: rows=${formatInteger(outputSummary.rowCount)}  columns=${formatInteger(columns)}${path}`
     );
+    if (outputSummary.isPartial === true) {
+      lines.push(
+        `  partial output: showing ${formatInteger(outputSummary.previewCount)} preview row(s) of ${formatInteger(outputSummary.totalCount)}`
+      );
+    }
   }
   for (const warning of warnings) {
     lines.push(`  warning: ${warning}`);
@@ -5474,6 +5680,11 @@ function exportPlayStatusRows(status, outPath) {
       `Run ${status.runId} did not expose a row-shaped final output to export.`
     );
   }
+  if (!rowsInfo.complete) {
+    throw new DeeplineError(
+      `Run output only includes ${rowsInfo.rows.length} preview row(s) of ${rowsInfo.totalRows}; full dataset export is not available from this status response yet.`
+    );
+  }
   return writeCanonicalRowsCsv(rowsInfo, outPath);
 }
 function renderServerResultView(value) {
@@ -5783,11 +5994,24 @@ async function handleFileBackedRun(options) {
   const progress = getActiveCliProgress() ?? createCliProgress(!options.jsonOutput);
   const absolutePlayPath = resolve7(options.target.path);
   progress.phase("compiling play");
-  const sourceCode = readFileSync3(absolutePlayPath, "utf-8");
+  const sourceCode = traceCliSync(
+    "cli.play_file_read_source",
+    { targetKind: "file" },
+    () => readFileSync3(absolutePlayPath, "utf-8")
+  );
+  const runtimeInput = options.input ? { ...options.input } : {};
   let graph;
   try {
-    graph = await collectBundledPlayGraph(absolutePlayPath);
-    await compileBundledPlayGraphManifests(client, graph);
+    graph = await traceCliSpan(
+      "cli.play_file_bundle_graph",
+      { targetKind: "file" },
+      () => collectBundledPlayGraph(absolutePlayPath)
+    );
+    await traceCliSpan(
+      "cli.play_file_compile_manifests",
+      { targetKind: "file" },
+      () => compileBundledPlayGraphManifests(client, graph)
+    );
     progress.phase("compiled play");
   } catch (error) {
     progress.fail();
@@ -5798,36 +6022,47 @@ async function handleFileBackedRun(options) {
   const playName = bundleResult.playName ?? extractPlayName(sourceCode, absolutePlayPath);
   try {
     progress.phase("publishing imported plays");
-    await publishImportedPlayDependencies(client, graph);
+    await traceCliSpan(
+      "cli.play_file_publish_imports",
+      { targetKind: "file" },
+      () => publishImportedPlayDependencies(client, graph)
+    );
   } catch (error) {
     progress.fail();
     console.error(error instanceof Error ? error.message : String(error));
     return 1;
   }
-  const runtimeInput = options.input ? { ...options.input } : {};
   const packagedFileUploads = bundleResult.packagedFiles.map(
     (file) => stageFile(file.logicalPath, file.absolutePath)
   );
+  const compilerManifest = requireCompilerManifest(bundleResult);
   const fileInputBindings = fileInputBindingsFromStaticPipeline(
-    requireCompilerManifest(bundleResult).staticPipeline
+    compilerManifest.staticPipeline
   );
   applyCsvShortcutInput({
     runtimeInput,
     bindings: fileInputBindings,
     fallbackInputPath: "file"
   });
-  const stagedFileInputs = await stageFileInputArgs({
-    client,
-    runtimeInput,
-    bindings: fileInputBindings,
-    progress
-  });
+  const stagedFileInputs = await traceCliSpan(
+    "cli.play_stage_inputs",
+    {
+      targetKind: "file",
+      bindingCount: fileInputBindings.length
+    },
+    () => stageFileInputArgs({
+      client,
+      runtimeInput,
+      bindings: fileInputBindings,
+      progress
+    })
+  );
   const startRequest = {
     name: playName,
     sourceCode: bundleResult.sourceCode,
     sourceFiles: bundleResult.sourceFiles,
     runtimeArtifact: bundleResult.artifact,
-    compilerManifest: requireCompilerManifest(bundleResult),
+    compilerManifest,
     packagedFileUploads,
     ...Object.keys(runtimeInput).length > 0 ? { input: runtimeInput } : {},
     ...stagedFileInputs.inputFile ? { inputFile: stagedFileInputs.inputFile } : {},
@@ -5836,26 +6071,42 @@ async function handleFileBackedRun(options) {
   };
   if (options.watch) {
     progress.phase("starting run");
-    const finalStatus = await startAndWaitForPlayCompletionByStream({
-      client,
-      request: startRequest,
-      playName,
-      jsonOutput: options.jsonOutput,
-      emitLogs: options.emitLogs,
-      waitTimeoutMs: options.waitTimeoutMs,
-      progress
-    });
-    const exportedPath = exportPlayStatusRows(finalStatus, options.outPath);
+    const finalStatus = await traceCliSpan(
+      "cli.play_start_watch",
+      { targetKind: "file", playName },
+      () => startAndWaitForPlayCompletionByStream({
+        client,
+        request: startRequest,
+        playName,
+        jsonOutput: options.jsonOutput,
+        emitLogs: options.emitLogs,
+        waitTimeoutMs: options.waitTimeoutMs,
+        progress
+      })
+    );
+    const exportedPath = traceCliSync(
+      "cli.play_export_rows",
+      { targetKind: "file", playName },
+      () => exportPlayStatusRows(finalStatus, options.outPath)
+    );
     if (finalStatus.status === "completed") {
       progress.complete();
     } else {
       progress.fail();
     }
-    writePlayResult(finalStatus, options.jsonOutput, { exportedPath });
+    traceCliSync(
+      "cli.play_write_result",
+      { targetKind: "file", playName },
+      () => writePlayResult(finalStatus, options.jsonOutput, { exportedPath })
+    );
     return finalStatus.status === "completed" ? 0 : 1;
   }
   progress.phase("starting run");
-  const started = await client.startPlayRun(startRequest);
+  const started = await traceCliSpan(
+    "cli.play_start_unwatched",
+    { targetKind: "file", playName },
+    () => client.startPlayRun(startRequest)
+  );
   const dashboardUrl = buildPlayDashboardUrl(client.baseUrl, playName);
   progress.phase(`loading play on ${dashboardUrl}`);
   progress.complete();
@@ -5890,32 +6141,67 @@ async function handleNamedRun(options) {
   }
   const client = new DeeplineClient();
   const progress = getActiveCliProgress() ?? createCliProgress(!options.jsonOutput);
-  progress.phase("loading play definition");
-  const playDetail = await assertCanonicalNamedPlayReference(client, options.target.name);
-  progress.phase("selecting revision");
-  const selectedRevisionId = await resolveNamedRunRevisionId({
-    client,
-    playName: options.target.name,
-    revisionId: options.revisionId,
-    selector: options.revisionSelector
-  });
+  const playName = options.target.name;
   const runtimeInput = options.input ? { ...options.input } : {};
-  const fileInputBindings = [
+  const needsPlayDefinition = namedRunNeedsPlayDefinition({
+    runtimeInput,
+    revisionSelector: options.revisionSelector
+  });
+  const playDetail = needsPlayDefinition ? await (async () => {
+    progress.phase("loading play definition");
+    return traceCliSpan(
+      "cli.play_load_definition",
+      { targetKind: "name", playName, skipped: false },
+      () => assertCanonicalNamedPlayReference(client, playName)
+    );
+  })() : (recordCliTrace({
+    phase: "cli.play_load_definition",
+    ms: 0,
+    ok: true,
+    targetKind: "name",
+    playName,
+    skipped: true
+  }), null);
+  progress.phase("selecting revision");
+  const selectedRevisionId = await traceCliSpan(
+    "cli.play_select_revision",
+    {
+      targetKind: "name",
+      playName,
+      selector: options.revisionSelector,
+      hasExplicitRevisionId: Boolean(options.revisionId)
+    },
+    () => resolveNamedRunRevisionId({
+      client,
+      playName,
+      revisionId: options.revisionId,
+      selector: options.revisionSelector
+    })
+  );
+  const fileInputBindings = playDetail ? [
     ...fileInputBindingsFromPlaySchema(playDetail.play.inputSchema),
     ...fileInputBindingsFromStaticPipeline(playDetail.play.staticPipeline)
-  ];
+  ] : [];
   applyCsvShortcutInput({
     runtimeInput,
     bindings: fileInputBindings
   });
-  const stagedFileInputs = await stageFileInputArgs({
-    client,
-    runtimeInput,
-    bindings: fileInputBindings,
-    progress
-  });
+  const stagedFileInputs = await traceCliSpan(
+    "cli.play_stage_inputs",
+    {
+      targetKind: "name",
+      playName,
+      bindingCount: fileInputBindings.length
+    },
+    () => stageFileInputArgs({
+      client,
+      runtimeInput,
+      bindings: fileInputBindings,
+      progress
+    })
+  );
   const startRequest = {
-    name: options.target.name,
+    name: playName,
     ...selectedRevisionId ? { revisionId: selectedRevisionId } : {},
     ...Object.keys(runtimeInput).length > 0 ? { input: runtimeInput } : {},
     ...stagedFileInputs.inputFile ? { inputFile: stagedFileInputs.inputFile } : {},
@@ -5924,35 +6210,51 @@ async function handleNamedRun(options) {
   };
   if (options.watch) {
     progress.phase("starting run");
-    const finalStatus = await startAndWaitForPlayCompletionByStream({
-      client,
-      request: startRequest,
-      playName: options.target.name,
-      jsonOutput: options.jsonOutput,
-      emitLogs: options.emitLogs,
-      waitTimeoutMs: options.waitTimeoutMs,
-      progress
-    });
-    const exportedPath = exportPlayStatusRows(finalStatus, options.outPath);
+    const finalStatus = await traceCliSpan(
+      "cli.play_start_watch",
+      { targetKind: "name", playName },
+      () => startAndWaitForPlayCompletionByStream({
+        client,
+        request: startRequest,
+        playName,
+        jsonOutput: options.jsonOutput,
+        emitLogs: options.emitLogs,
+        waitTimeoutMs: options.waitTimeoutMs,
+        progress
+      })
+    );
+    const exportedPath = traceCliSync(
+      "cli.play_export_rows",
+      { targetKind: "name", playName },
+      () => exportPlayStatusRows(finalStatus, options.outPath)
+    );
     if (finalStatus.status === "completed") {
       progress.complete();
     } else {
       progress.fail();
     }
-    writePlayResult(finalStatus, options.jsonOutput, { exportedPath });
+    traceCliSync(
+      "cli.play_write_result",
+      { targetKind: "name", playName },
+      () => writePlayResult(finalStatus, options.jsonOutput, { exportedPath })
+    );
     return finalStatus.status === "completed" ? 0 : 1;
   }
   progress.phase("starting run");
-  const started = await client.startPlayRun(startRequest);
+  const started = await traceCliSpan(
+    "cli.play_start_unwatched",
+    { targetKind: "name", playName },
+    () => client.startPlayRun(startRequest)
+  );
   const dashboardUrl = buildPlayDashboardUrl(
     client.baseUrl,
-    options.target.name
+    playName
   );
   progress.phase(`loading play on ${dashboardUrl}`);
   progress.complete();
   writeStartedPlayRun({
     runId: started.workflowId,
-    playName: started.name ?? options.target.name,
+    playName: started.name ?? playName,
     status: started.status,
     statusUrl: started.statusUrl,
     dashboardUrl: started.dashboardUrl ?? dashboardUrl,
@@ -7815,54 +8117,6 @@ async function syncSdkSkillsIfNeeded(baseUrl) {
   writeSdkSkillsStatusLine("SDK skills are up to date.");
 }
 
-// src/cli/trace.ts
-var cliTraceStartedAt = Date.now();
-function isTruthyEnv(value) {
-  return value === "1" || value === "true" || value === "yes";
-}
-function isCliTraceEnabled() {
-  return isTruthyEnv(process.env.DEEPLINE_CLI_TRACE);
-}
-function recordCliTrace(event) {
-  if (!isCliTraceEnabled()) {
-    return;
-  }
-  const now = Date.now();
-  const payload = {
-    ts: now,
-    source: "cli",
-    sinceStartMs: now - cliTraceStartedAt,
-    ...event
-  };
-  process.stderr.write(`[cli-trace] ${JSON.stringify(payload)}
-`);
-}
-async function traceCliSpan(phase, fields, run) {
-  if (!isCliTraceEnabled()) {
-    return run();
-  }
-  const startedAt = Date.now();
-  try {
-    const result = await run();
-    recordCliTrace({
-      phase,
-      ms: Date.now() - startedAt,
-      ok: true,
-      ...fields
-    });
-    return result;
-  } catch (error) {
-    recordCliTrace({
-      phase,
-      ms: Date.now() - startedAt,
-      ok: false,
-      error: error instanceof Error ? error.message : String(error),
-      ...fields
-    });
-    throw error;
-  }
-}
-
 // src/cli/index.ts
 function shouldPrintStartupPhase() {
   if (process.argv.includes("--json")) {
@@ -7873,6 +8127,12 @@ function shouldPrintStartupPhase() {
   const subcommand = args[1];
   return (command === "play" || command === "plays") && subcommand === "run";
 }
+function shouldDeferSkillsSyncForCommand() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const subcommand = args[1];
+  return (command === "play" || command === "plays") && subcommand === "run" && args.includes("--json");
+}
 async function main() {
   const mainStartedAt = Date.now();
   recordCliTrace({
@@ -7917,11 +8177,13 @@ Output:
     if (printStartupPhase) {
       progress?.phase("checking sdk skills");
     }
-    await traceCliSpan(
-      "cli.sdk_skills_sync",
-      { baseUrl },
-      () => syncSdkSkillsIfNeeded(baseUrl)
-    );
+    if (!shouldDeferSkillsSyncForCommand()) {
+      await traceCliSpan(
+        "cli.sdk_skills_sync",
+        { baseUrl },
+        () => syncSdkSkillsIfNeeded(baseUrl)
+      );
+    }
   });
   registerAuthCommands(program);
   registerToolsCommands(program);