deepline 0.1.85 → 0.1.89

package/dist/cli/index.mjs

@@ -206,10 +206,10 @@ import { join as join2 } from "path";
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.85",
+  version: "0.1.89",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.85",
+    latest: "0.1.89",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -223,6 +223,7 @@ var SDK_API_CONTRACT = SDK_RELEASE.apiContract;
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
 var COORDINATOR_URL_OVERRIDE_HEADER = "x-deepline-coordinator-url";
 var WORKER_CALLBACK_URL_OVERRIDE_HEADER = "x-deepline-worker-callback-url";
+var SYNTHETIC_RUN_HEADER = "x-deepline-synthetic-run";
 
 // src/http.ts
 var MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
@@ -290,6 +291,10 @@ var HttpClient = class {
     if (workerCallbackUrl?.trim()) {
       headers[WORKER_CALLBACK_URL_OVERRIDE_HEADER] = workerCallbackUrl.trim();
     }
+    const syntheticRun = typeof process !== "undefined" ? process.env?.DEEPLINE_SYNTHETIC_RUN : void 0;
+    if (syntheticRun && syntheticRun.trim() && syntheticRun.trim() !== "0") {
+      headers[SYNTHETIC_RUN_HEADER] = "1";
+    }
     return headers;
   }
   /**
@@ -556,7 +561,7 @@ function decodeSseFrame(frame) {
   return parsed;
 }
 function sleep(ms) {
-  return new Promise((resolve13) => setTimeout(resolve13, ms));
+  return new Promise((resolve14) => setTimeout(resolve14, ms));
 }
 
 // src/client.ts
@@ -566,7 +571,7 @@ var EXECUTE_RESPONSE_CONTRACT_HEADER = "x-deepline-execute-response-contract";
 var V2_EXECUTE_RESPONSE_CONTRACT = "v2-tool-response";
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 function sleep2(ms) {
-  return new Promise((resolve13) => setTimeout(resolve13, ms));
+  return new Promise((resolve14) => setTimeout(resolve14, ms));
 }
 function isTransientCompileManifestError(error) {
   if (error instanceof DeeplineError && typeof error.statusCode === "number") {
@@ -580,6 +585,21 @@ function isTransientCompileManifestError(error) {
 function isRecord(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
+function isPrebuiltPlayDescription(play) {
+  return play.origin === "prebuilt" || play.ownerType === "deepline";
+}
+function preferPrebuiltPlayDescriptions(plays) {
+  const prebuilt = [];
+  const owned = [];
+  for (const play of plays) {
+    if (isPrebuiltPlayDescription(play)) {
+      prebuilt.push(play);
+    } else {
+      owned.push(play);
+    }
+  }
+  return [...prebuilt, ...owned];
+}
 function isPlayRunPackage(value) {
   return Boolean(
     value && typeof value === "object" && !Array.isArray(value) && value.kind === "play_run" && value.run && typeof value.run?.id === "string"
@@ -703,8 +723,14 @@ function playRunStatusFromState(state) {
 var DeeplineClient = class {
   http;
   config;
+  /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
   runs;
   /**
+   * Create a low-level SDK client.
+   *
+   * Most callers can omit options and let the SDK resolve auth/config from
+   * environment variables and CLI-managed credentials.
+   *
    * @param options - Optional overrides for API key, base URL, timeout, and retries.
    * @throws {@link ConfigError} if no API key can be resolved from any source.
    */
@@ -806,12 +832,19 @@ var DeeplineClient = class {
   // ——————————————————————————————————————————————————————————
   // Secrets
   // ——————————————————————————————————————————————————————————
+  /** List secret metadata visible to the current workspace. */
   async listSecrets() {
     const response = await this.http.get(
       "/api/v2/secrets"
     );
     return Array.isArray(response.secrets) ? response.secrets : [];
   }
+  /**
+   * Check whether a named secret exists, is active, and has a stored value.
+   *
+   * @param name - Secret name. It is normalized to uppercase before lookup.
+   * @returns Matching active secret metadata, or `null`.
+   */
   async checkSecret(name) {
     const normalized = name.trim().toUpperCase();
     const secrets = await this.listSecrets();
@@ -924,9 +957,21 @@ var DeeplineClient = class {
       headers
     );
   }
+  /**
+   * Back-compatible alias for {@link executeTool}.
+   *
+   * Retained for callers that still use the older raw naming while the response
+   * envelope remains the same.
+   */
   async executeToolRaw(toolId, input2, options) {
     return this.executeTool(toolId, input2, options);
   }
+  /**
+   * Run a bounded SQL query against the customer data plane.
+   *
+   * Use this from trusted backend or agent contexts only. The API enforces
+   * workspace scoping and row limits.
+   */
   async queryCustomerDb(input2) {
     return this.http.post("/api/v2/db/query", {
       sql: input2.sql,
@@ -998,6 +1043,17 @@ var DeeplineClient = class {
     );
     return normalizePlayRunStart(response);
   }
+  /**
+   * Start a play run and stream live runtime events from the same request.
+   *
+   * Use this when a caller wants low-level event handling instead of submitting
+   * first and then connecting to `streamPlayRunEvents(runId)`.
+   *
+   * @param request - Play run configuration.
+   * @param options - Optional streaming options.
+   * @param options.signal - Optional abort signal for the streaming request.
+   * @returns Async stream of play-scoped live events.
+   */
   async *startPlayRunStream(request, options) {
     const body = {
       ...request.name ? { name: request.name } : {},
@@ -1050,6 +1106,12 @@ var DeeplineClient = class {
       compilerManifest
     });
   }
+  /**
+   * Register multiple bundled play artifacts in one request.
+   *
+   * Used by packaging and prebuilt publication flows. Each artifact is compiled
+   * first when a compiler manifest is not already supplied.
+   */
   async registerPlayArtifacts(artifacts) {
     const compiledArtifacts = await Promise.all(
       artifacts.map(async (artifact) => ({
@@ -1066,6 +1128,13 @@ var DeeplineClient = class {
       artifacts: compiledArtifacts
     });
   }
+  /**
+   * Compile a bundled play artifact into the server-side compiler manifest.
+   *
+   * The manifest records imports, trigger bindings, static pipeline shape, and
+   * runtime metadata needed before a play artifact can be checked, registered,
+   * or run.
+   */
   async compilePlayManifest(input2) {
     const retryDelays = COMPILE_MANIFEST_RETRY_DELAYS_MS.slice(
       0,
@@ -1094,9 +1163,21 @@ var DeeplineClient = class {
   async checkPlayArtifact(input2) {
     return this.http.post("/api/v2/plays/check", input2);
   }
+  /**
+   * Compile legacy enrich command arguments into a runtime plan.
+   *
+   * This is primarily used by CLI compatibility paths that translate older
+   * enrichment commands onto the play runtime.
+   */
   async compileEnrichPlan(input2) {
     return this.http.post("/api/v2/enrich/compile", input2);
   }
+  /**
+   * Register an already-bundled play artifact and start a run from it.
+   *
+   * This is the low-level file-backed run path used by SDK/CLI packaging
+   * wrappers after local bundling has produced the runtime artifact.
+   */
   async startPlayRunFromBundle(input2) {
     const compilerManifest = input2.compilerManifest ?? await this.compilePlayManifest({
       name: input2.name,
@@ -1254,6 +1335,12 @@ var DeeplineClient = class {
     const response = await this.http.postFormData("/api/v2/plays/files/stage", buildFormData);
     return response.files;
   }
+  /**
+   * Resolve staged play files by content hash without uploading bytes.
+   *
+   * Missing files are returned so callers can upload only the files the server
+   * does not already have.
+   */
   async resolveStagedPlayFiles(files) {
     return this.http.post("/api/v2/plays/files/stage", { files });
   }
@@ -1470,6 +1557,12 @@ var DeeplineClient = class {
       entries
     };
   }
+  /**
+   * Export persisted runtime-sheet rows for a play dataset/table namespace.
+   *
+   * This is the SDK form of exporting `ctx.dataset(...).run()` output for a
+   * specific play and optional run id.
+   */
   async getPlaySheetRows(input2) {
     const params = new URLSearchParams({
       tableNamespace: input2.tableNamespace,
@@ -1498,6 +1591,12 @@ var DeeplineClient = class {
       options?.reason ? { reason: options.reason } : {}
     );
   }
+  /**
+   * List callable plays visible to the workspace.
+   *
+   * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
+   * `origin: "owned"` for org-owned plays.
+   */
   async listPlays(options) {
     const params = new URLSearchParams();
     if (options?.origin) params.set("origin", options.origin);
@@ -1512,15 +1611,32 @@ var DeeplineClient = class {
     );
     return response.plays ?? [];
   }
+  /**
+   * Search callable plays and return compact play descriptions.
+   *
+   * Prebuilt plays are preferred by default because they have maintained
+   * contracts and stable run behavior.
+   */
   async searchPlays(options) {
     const params = new URLSearchParams();
     params.set("search", options.query.trim());
+    const scope = options.scope ?? "prebuilt";
+    if (scope !== "all") {
+      params.set("origin", scope);
+    }
     const response = await this.http.get(
       `/api/v2/plays?${params.toString()}`
     );
-    return (response.plays ?? []).map(
+    const plays = (response.plays ?? []).map(
       (play) => this.summarizePlayListItem(play, options)
     );
+    if (scope === "prebuilt") {
+      return plays.filter(isPrebuiltPlayDescription);
+    }
+    if (scope === "owned") {
+      return plays.filter((play) => !isPrebuiltPlayDescription(play));
+    }
+    return preferPrebuiltPlayDescriptions(plays);
   }
   /**
    * Get the full definition and state of a named play.
@@ -1543,6 +1659,12 @@ var DeeplineClient = class {
     const encodedName = encodeURIComponent(name);
     return this.http.get(`/api/v2/plays/${encodedName}`);
   }
+  /**
+   * Get a normalized play description suitable for agents and CLIs.
+   *
+   * The description includes runnable examples, input/output summaries, clone
+   * guidance, revision state, and latest run metadata when available.
+   */
   async describePlay(name, options) {
     const detail = await this.getPlay(name);
     return this.summarizePlayDetail(detail, options);
@@ -2409,7 +2531,7 @@ function buildCandidateUrls2(url) {
   }
 }
 function sleep3(ms) {
-  return new Promise((resolve13) => setTimeout(resolve13, ms));
+  return new Promise((resolve14) => setTimeout(resolve14, ms));
 }
 function printDeeplineLogo() {
   if (process.stdout.isTTY && (process.stdout.columns ?? 80) >= 70) {
@@ -4677,7 +4799,12 @@ function readPackageVersionFromPackageJson(packageJsonPath, packageName) {
   return null;
 }
 function findPackageJsonPathFrom(startDir, packageName) {
-  let current = resolve6(startDir);
+  if (!isAbsolute(startDir)) {
+    throw new Error(
+      `Package resolution requires an absolute start directory, got ${startDir}`
+    );
+  }
+  let current = startDir;
   while (true) {
     const packageJsonPath = join4(
       current,
@@ -4697,17 +4824,15 @@ function findPackageJsonPathFrom(startDir, packageName) {
 }
 function findPackageJsonPath(packageName, fromFile, adapter) {
   const startDirs = [
-    dirname5(fromFile),
-    adapter.projectRoot,
-    dirname5(adapter.sdkPackageJson),
-    process.cwd()
+    resolve6(dirname5(fromFile)),
+    resolve6(adapter.projectRoot),
+    resolve6(dirname5(adapter.sdkPackageJson))
   ];
   const seen = /* @__PURE__ */ new Set();
   for (const startDir of startDirs) {
-    const normalized = resolve6(startDir);
-    if (seen.has(normalized)) continue;
-    seen.add(normalized);
-    const packageJsonPath = findPackageJsonPathFrom(normalized, packageName);
+    if (seen.has(startDir)) continue;
+    seen.add(startDir);
+    const packageJsonPath = findPackageJsonPathFrom(startDir, packageName);
     if (packageJsonPath) return packageJsonPath;
   }
   const adapterNodeModulesPackageJson = join4(
@@ -5165,13 +5290,13 @@ async function writeArtifactCache(artifact, adapter) {
     "utf-8"
   );
 }
-function normalizeSourceMapForRuntime(sourceMapText) {
+function normalizeSourceMapForRuntime(sourceMapText, projectRoot) {
   const parsed = JSON.parse(sourceMapText);
   parsed.sources = (parsed.sources ?? []).map((sourcePath) => {
     if (sourcePath.startsWith("data:") || sourcePath.startsWith("node:") || sourcePath.startsWith("/") || /^[a-zA-Z]+:\/\//.test(sourcePath)) {
       return sourcePath;
     }
-    return resolve6(process.cwd(), sourcePath);
+    return join4(projectRoot, sourcePath);
   });
   parsed.sourceRoot = void 0;
   return JSON.stringify(parsed);
@@ -5437,7 +5562,10 @@ workers-harness:${harnessFingerprint}`
       };
     }
     const { bundledCode, sourceMapText, outputExtension } = buildOutcome;
-    const normalizedSourceMap = normalizeSourceMapForRuntime(sourceMapText);
+    const normalizedSourceMap = normalizeSourceMapForRuntime(
+      sourceMapText,
+      resolve6(adapter.projectRoot)
+    );
     const virtualBaseName = exportName === "default" ? basename(absolutePath).replace(/\.[^.]+$/, "") : `${basename(absolutePath).replace(/\.[^.]+$/, "")}.${exportName}`;
     const virtualFilename = `/virtual/deepline-plays/${analysis.graphHash}/${virtualBaseName}.${outputExtension}`;
     const executableCode = `${bundledCode}
@@ -7845,7 +7973,7 @@ function traceCliSync(phase, fields, run) {
   }
 }
 function sleep4(ms) {
-  return new Promise((resolve13) => setTimeout(resolve13, ms));
+  return new Promise((resolve14) => setTimeout(resolve14, ms));
 }
 function parseReferencedPlayTarget2(target) {
   const trimmed = target.trim();
@@ -8364,6 +8492,8 @@ var TERMINAL_PLAY_STATUSES2 = /* @__PURE__ */ new Set([
   "cancelled"
 ]);
 var PLAY_START_TRANSIENT_RETRY_DELAYS_MS = [500, 1500];
+var PLAY_PROGRESS_HEARTBEAT_INTERVAL_MS = 15e3;
+var PLAY_STATUS_HEARTBEAT_INTERVAL_MS = 15e3;
 function getEventPayload(event) {
   return event.payload && typeof event.payload === "object" ? event.payload : {};
 }
@@ -8424,6 +8554,7 @@ function extractTableNamespaceFromLiveEvent(event) {
   const payload = getEventPayload(event);
   const candidates = [
     payload.artifactTableNamespace,
+    payload.activeArtifactTableNamespace,
     payload.tableNamespace,
     payload.mapNodeId
   ];
@@ -8502,6 +8633,20 @@ function formatProgressCounts(input2) {
   const failed = typeof input2.failed === "number" && Number.isFinite(input2.failed) && input2.failed > 0 ? `, failed ${formatInteger(input2.failed)}` : "";
   return `${formatInteger(completed)}/${formatInteger(total)} (${percent}%)${failed}`;
 }
+function formatProgressMessageSuffix(input2) {
+  const message = typeof input2.message === "string" ? input2.message.trim() : "";
+  if (!message) {
+    return "";
+  }
+  const completed = typeof input2.completed === "number" && Number.isFinite(input2.completed) ? input2.completed : null;
+  if (/^[\d,]+\s*\/\s*[\d,]+\s+rows processed$/i.test(message)) {
+    return "";
+  }
+  if (completed !== null && completed > 0 && /rows?\s+queued\b/i.test(message)) {
+    return "";
+  }
+  return ` - ${message}`;
+}
 function getProgressLinesFromLiveEvent(event) {
   const payload = getEventPayload(event);
   if (event.type === "play.step.progress") {
@@ -8511,7 +8656,13 @@ function getProgressLinesFromLiveEvent(event) {
       failed: payload.failed
     });
     if (!counts) return [];
-    return [`progress ${formatProgressLabel(payload.stepId)}: ${counts}`];
+    const messageSuffix = formatProgressMessageSuffix({
+      message: payload.message,
+      completed: payload.completed
+    });
+    return [
+      `progress ${formatProgressLabel(payload.stepId)}: ${counts}${messageSuffix}`
+    ];
   }
   if (event.type !== "play.run.snapshot" && event.type !== "play.run.final_status") {
     return [];
@@ -8535,22 +8686,69 @@ function getProgressLinesFromLiveEvent(event) {
     if (!counts) {
       continue;
     }
+    const messageSuffix = formatProgressMessageSuffix({
+      message: progress.message,
+      completed: progress.completed
+    });
     lines.push(
-      `progress ${formatProgressLabel(record.nodeId ?? progress.artifactTableNamespace)}: ${counts}`
+      `progress ${formatProgressLabel(record.nodeId ?? progress.artifactTableNamespace)}: ${counts}${messageSuffix}`
     );
   }
   return lines;
 }
+function shouldPrintPlayProgressLine(input2) {
+  if (!input2.signature) {
+    return false;
+  }
+  return input2.lastProgressSignature !== input2.signature || input2.nowMs - input2.lastProgressHeartbeatAt >= PLAY_PROGRESS_HEARTBEAT_INTERVAL_MS;
+}
 function printPlayProgressLines(input2) {
   for (const line of input2.lines) {
     const signature = line.trim();
-    if (!signature || input2.state.lastProgressSignature === signature) {
+    const now = Date.now();
+    if (!shouldPrintPlayProgressLine({
+      signature,
+      lastProgressSignature: input2.state.lastProgressSignature,
+      lastProgressHeartbeatAt: input2.state.lastProgressHeartbeatAt,
+      nowMs: now
+    })) {
       continue;
     }
     input2.state.lastProgressSignature = signature;
+    input2.state.lastProgressHeartbeatAt = now;
     input2.progress.writeLine(line);
   }
 }
+function getRunningHeartbeatLine(input2) {
+  const status = getStatusFromLiveEvent(input2.event);
+  if (status !== "queued" && status !== "running" && status !== "waiting") {
+    return null;
+  }
+  const tableNamespace = extractTableNamespaceFromLiveEvent(input2.event);
+  const target = tableNamespace ? formatProgressLabel(tableNamespace) : input2.playName;
+  if (status === "queued") {
+    return `queued ${target}: waiting for worker capacity`;
+  }
+  if (status === "waiting") {
+    return `waiting ${target}: waiting on external work`;
+  }
+  return `running ${target}: still processing`;
+}
+function printPlayStatusHeartbeat(input2) {
+  const now = Date.now();
+  if (now - input2.state.lastStatusHeartbeatAt < PLAY_STATUS_HEARTBEAT_INTERVAL_MS) {
+    return;
+  }
+  const line = getRunningHeartbeatLine({
+    event: input2.event,
+    playName: input2.playName
+  });
+  if (!line) {
+    return;
+  }
+  input2.state.lastStatusHeartbeatAt = now;
+  input2.progress.writeLine(line);
+}
 function buildPlayDashboardUrl(baseUrl, playName) {
   const trimmedBase = baseUrl.replace(/\/$/, "");
   const encodedPlayName = encodeURIComponent(playName);
@@ -8633,11 +8831,20 @@ async function waitForPlayCompletionByStream(input2) {
         progress: input2.progress
       });
       if (!input2.jsonOutput) {
+        const progressLines = getProgressLinesFromLiveEvent(event);
         printPlayProgressLines({
-          lines: getProgressLinesFromLiveEvent(event),
+          lines: progressLines,
           state: input2.state,
           progress: input2.progress
         });
+        if (progressLines.length === 0) {
+          printPlayStatusHeartbeat({
+            event,
+            playName: input2.playName,
+            state: input2.state,
+            progress: input2.progress
+          });
+        }
       }
       const finalStatus = getFinalStatusFromLiveEvent(event);
       if (finalStatus) {
@@ -8715,7 +8922,9 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
   const state = {
     lastLogIndex: 0,
     emittedRunnerStarted: false,
-    lastProgressSignature: null
+    lastProgressSignature: null,
+    lastProgressHeartbeatAt: 0,
+    lastStatusHeartbeatAt: 0
   };
   const controller = new AbortController();
   let timedOut = false;
@@ -8756,7 +8965,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
           dashboardUrl,
           noOpen: input2.noOpen
         });
-        input2.progress.phase(`loading play on ${dashboardUrl}`);
+        input2.progress.phase("running");
         emittedDashboardUrl = true;
       }
       assertPlayWaitNotTimedOut({
@@ -8787,11 +8996,20 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
         progress: input2.progress
       });
       if (!input2.jsonOutput) {
+        const progressLines = getProgressLinesFromLiveEvent(event);
         printPlayProgressLines({
-          lines: getProgressLinesFromLiveEvent(event),
+          lines: progressLines,
           state,
           progress: input2.progress
         });
+        if (progressLines.length === 0) {
+          printPlayStatusHeartbeat({
+            event,
+            playName: input2.playName,
+            state,
+            progress: input2.progress
+          });
+        }
       }
       const finalStatus = getFinalStatusFromLiveEvent(event);
       if (finalStatus) {
@@ -9391,6 +9609,17 @@ function getPlayRunPackage(status) {
   const packaged = status.package;
   return isPlayRunPackageValue(packaged) ? packaged : null;
 }
+function withTerminalPlayIdentity(status, playName) {
+  if (!playName.trim() || getPlayRunPackage(status)) {
+    return status;
+  }
+  const record = status;
+  const hasIdentity = typeof record.playName === "string" && record.playName.trim().length > 0 || typeof record.name === "string" && record.name.trim().length > 0 || Boolean(getStringField(record.run, "playName"));
+  if (hasIdentity) {
+    return status;
+  }
+  return { ...status, playName };
+}
 function compactPlayStatus(status) {
   const packaged = getPlayRunPackage(status);
   if (packaged) {
@@ -9567,6 +9796,9 @@ function actionToCommand(action) {
   if (record.kind === "deepline_run_inspect" && typeof record.runId === "string") {
     return `deepline runs get ${record.runId} --json`;
   }
+  if (record.kind === "deepline_run_billing" && typeof record.runId === "string") {
+    return `deepline runs get ${record.runId} --full --json | jq '.billing'`;
+  }
   if (record.kind === "deepline_run_export" && typeof record.runId === "string" && typeof record.datasetPath === "string") {
     return `deepline runs export ${record.runId} --dataset ${shellSingleQuote(
       record.datasetPath
@@ -9599,6 +9831,12 @@ function buildRunPackageTextLines(packaged) {
   if (playName) {
     lines.push(`  play: ${playName}`);
   }
+  const next = packaged.next && typeof packaged.next === "object" && !Array.isArray(packaged.next) ? packaged.next : {};
+  const billingCommand = actionToCommand(next.billing);
+  if (billingCommand) {
+    const costState = status === "completed" || status === "failed" || status === "cancelled" ? "finalizing" : "pending";
+    lines.push(`  cost: ${costState}`);
+  }
   for (const step of readRecordArray(packaged.steps).slice(0, 8)) {
     const id = typeof step.id === "string" ? step.id : "step";
     const kind = typeof step.kind === "string" ? step.kind : "step";
@@ -9615,12 +9853,12 @@ function buildRunPackageTextLines(packaged) {
       );
     }
   }
-  const next = packaged.next && typeof packaged.next === "object" && !Array.isArray(packaged.next) ? packaged.next : {};
   const datasetActions = readFirstDatasetActions(packaged);
   const inspectCommand = actionToCommand(next.inspect);
   const queryCommand = actionToCommand(next.query) ?? actionToCommand(datasetActions.query);
   const exportCommand = actionToCommand(next.export) ?? actionToCommand(datasetActions.exportCsv);
   if (inspectCommand) lines.push(`  inspect: ${inspectCommand}`);
+  if (billingCommand) lines.push(`  billing: ${billingCommand}`);
   if (queryCommand) lines.push(`  query: ${queryCommand}`);
   if (exportCommand) lines.push(`  export CSV: ${exportCommand}`);
   return lines;
@@ -10662,11 +10900,14 @@ async function handleFileBackedRun(options) {
     } else {
       progress.fail();
     }
-    const outputStatus = await resolvePlayRunOutputStatus({
-      client,
-      status: finalStatus,
-      fullJson: options.fullJson
-    });
+    const outputStatus = withTerminalPlayIdentity(
+      await resolvePlayRunOutputStatus({
+        client,
+        status: finalStatus,
+        fullJson: options.fullJson
+      }),
+      playName
+    );
     traceCliSync(
       "cli.play_write_result",
       { targetKind: "file", playName },
@@ -10689,7 +10930,7 @@ async function handleFileBackedRun(options) {
     dashboardUrl: resolvedDashboardUrl,
     noOpen: options.noOpen
   });
-  progress.phase(`loading play on ${resolvedDashboardUrl}`);
+  progress.phase("started run");
   progress.complete();
   writeStartedPlayRun({
     runId: started.workflowId,
@@ -10809,11 +11050,14 @@ async function handleNamedRun(options) {
     } else {
       progress.fail();
     }
-    const outputStatus = await resolvePlayRunOutputStatus({
-      client,
-      status: finalStatus,
-      fullJson: options.fullJson
-    });
+    const outputStatus = withTerminalPlayIdentity(
+      await resolvePlayRunOutputStatus({
+        client,
+        status: finalStatus,
+        fullJson: options.fullJson
+      }),
+      playName
+    );
     traceCliSync(
       "cli.play_write_result",
       { targetKind: "name", playName },
@@ -10836,7 +11080,7 @@ async function handleNamedRun(options) {
     dashboardUrl: resolvedDashboardUrl,
     noOpen: options.noOpen
   });
-  progress.phase(`loading play on ${resolvedDashboardUrl}`);
+  progress.phase("started run");
   progress.complete();
   writeStartedPlayRun({
     runId: started.workflowId,
@@ -11324,16 +11568,19 @@ function parsePlaySearchOptions(args) {
   const query = args[0]?.trim();
   if (!query) {
     throw new Error(
-      "Usage: deepline plays search <query> [--compact] [--json]"
+      "Usage: deepline plays search <query> [--all] [--compact] [--json]"
     );
   }
   return {
     query,
     jsonOutput: argsWantJson(args),
     compact: args.includes("--compact"),
-    prebuiltOnly: args.includes("--prebuilt")
+    scope: args.includes("--all") && !args.includes("--prebuilt") ? "all" : "prebuilt"
   };
 }
+function playSearchDisclaimer(scope) {
+  return scope === "all" ? "Prebuilt-first search: Deepline-managed prebuilts are trusted, robust plays with maintained contracts, so they are listed before plays you created. Use created-play results only when you are specifically looking for one." : "Prebuilt-first search: Deepline-managed prebuilts are trusted, robust plays with maintained contracts. Plays you created are omitted by default; add --all only when you are specifically looking for one.";
+}
 function printPlayDescription(play) {
   const reference = formatPlayListReference(play);
   const labels = [
@@ -11475,19 +11722,26 @@ async function handlePlaySearch(args) {
     return 1;
   }
   const client = new DeeplineClient();
-  const plays = (await client.searchPlays({
+  const plays = await client.searchPlays({
     query: options.query,
-    compact: options.compact
-  })).filter(
-    (play) => options.prebuiltOnly ? play.origin === "prebuilt" || play.ownerType === "deepline" : true
-  );
+    compact: options.compact,
+    scope: options.scope
+  });
+  const disclaimer = playSearchDisclaimer(options.scope);
   if (options.jsonOutput) {
-    const jsonPlays = options.prebuiltOnly ? plays.map((play) => ({
+    const jsonPlays = options.scope === "prebuilt" ? plays.map((play) => ({
       ...play,
       inputSchema: compactPlaySchema(play.inputSchema)
     })) : plays;
     process.stdout.write(
       `${JSON.stringify({
+        disclaimer,
+        search_policy: {
+          default_scope: "prebuilt",
+          included_origins: options.scope === "all" ? ["prebuilt", "owned"] : ["prebuilt"],
+          owned_plays_omitted: options.scope === "prebuilt",
+          include_owned_flag: "--all"
+        },
         plays: jsonPlays,
         total: jsonPlays.length,
         truncated: false
@@ -11496,21 +11750,23 @@ async function handlePlaySearch(args) {
     );
     return 0;
   }
-  const displayPlays = options.prebuiltOnly ? plays.slice(0, 5) : plays;
+  const displayPlays = options.scope === "prebuilt" ? plays.slice(0, 5) : plays;
+  process.stdout.write(`${disclaimer}
+`);
   process.stdout.write(
-    `${plays.length} plays found${options.prebuiltOnly && plays.length > displayPlays.length ? `; showing top ${displayPlays.length}` : ""}:
+    `${plays.length} plays found${options.scope === "prebuilt" && plays.length > displayPlays.length ? `; showing top ${displayPlays.length}` : ""}:
 
 `
   );
   for (const play of displayPlays) {
-    if (options.prebuiltOnly) {
+    if (options.scope === "prebuilt") {
       printCompactPlaySearchResult(play);
     } else {
       printPlayDescription(play);
     }
     console.log("");
   }
-  if (options.prebuiltOnly && plays.length > displayPlays.length) {
+  if (options.scope === "prebuilt" && plays.length > displayPlays.length) {
     console.log("Use --json for the full machine-readable result set.");
   }
   return 0;
@@ -11964,18 +12220,26 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  const addPlaySearchCommand = (command) => command.description("Search saved and prebuilt plays.").option("--prebuilt", "Only show Deepline-managed prebuilt plays").addHelpText(
+  const addPlaySearchCommand = (command) => command.description("Search Deepline prebuilt plays by task.").option(
+    "--prebuilt",
+    "Only show Deepline-managed prebuilt plays (default)"
+  ).option(
+    "--all",
+    "Also include plays you created after Deepline-managed prebuilts"
+  ).addHelpText(
     "after",
     `
 Notes:
-  Ranked discovery for workflows. Use describe on a result before running it.
-  Prefer --prebuilt for new GTM tasks so old workspace scratchpads do not
-  outrank Deepline-managed routes unless the user names one explicitly.
+  Ranked discovery for workflows. Search defaults to Deepline-managed prebuilts
+  because they are trusted, robust plays with maintained contracts. Use describe
+  on a result before running it.
+  Add --all only when you are specifically looking for a play you created.
   The grep alias is the same ranked retrieval surface with a more literal name
   for agents that are filtering the play registry.
 
 Examples:
   deepline plays search email
+  deepline plays search email --all
   deepline plays grep "linkedin to email" --compact --json
   deepline plays describe person-linkedin-to-email --json
 `
@@ -11983,6 +12247,7 @@ Examples:
     process.exitCode = await handlePlaySearch([
       query,
       ...options.prebuilt ? ["--prebuilt"] : [],
+      ...options.all ? ["--all"] : [],
       ...options.compact ? ["--compact"] : [],
       ...options.json ? ["--json"] : []
     ]);
@@ -13750,7 +14015,7 @@ async function readHiddenLine(prompt) {
   if (typeof input.setRawMode === "function") input.setRawMode(true);
   let value = "";
   input.resume();
-  return await new Promise((resolve13, reject) => {
+  return await new Promise((resolve14, reject) => {
     let settled = false;
     const cleanup = () => {
       input.off("data", onData);
@@ -13765,7 +14030,7 @@ async function readHiddenLine(prompt) {
       settled = true;
       output.write("\n");
       cleanup();
-      resolve13(line);
+      resolve14(line);
     };
     const fail = (error) => {
       if (settled) return;
@@ -13937,9 +14202,15 @@ Examples:
 
 // src/cli/commands/tools.ts
 import { Option } from "commander";
-import { chmodSync, mkdtempSync, writeFileSync as writeFileSync9 } from "fs";
+import {
+  chmodSync,
+  existsSync as existsSync8,
+  mkdtempSync,
+  readFileSync as readFileSync7,
+  writeFileSync as writeFileSync9
+} from "fs";
 import { tmpdir as tmpdir4 } from "os";
-import { join as join10 } from "path";
+import { join as join10, resolve as resolve12 } from "path";
 
 // src/tool-output.ts
 import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync8 } from "fs";
@@ -14530,7 +14801,13 @@ Examples:
   ).option(
     "--json [payload]",
     "Emit JSON output. Use `--input` or `--payload` for passing JSON params."
-  ).option("--input <payload>", "Merge a JSON object into the tool params").option("--payload <payload>", "Merge a JSON object into the tool params").option(
+  ).option(
+    "--input <payload>",
+    "Merge a JSON object or @file path into the tool params"
+  ).option(
+    "--payload <payload>",
+    "Merge a JSON object or @file path into the tool params"
+  ).option(
     "--output-format <format>",
     "Output format: auto, csv, csv_file, json, or json_file"
   ).option(
@@ -15101,6 +15378,57 @@ function normalizeOutputFormat(raw) {
       throw new Error(`Invalid value for --output-format: ${raw}`);
   }
 }
+function resolveAtFilePath(rawPath) {
+  const trimmed = rawPath.trim();
+  const resolved = resolve12(trimmed);
+  if (existsSync8(resolved)) return resolved;
+  if (process.platform !== "win32" && trimmed.includes("\\")) {
+    const normalized = resolve12(trimmed.replace(/\\/g, "/"));
+    if (existsSync8(normalized)) return normalized;
+  }
+  return resolved;
+}
+function readJsonArgument(raw, flagName) {
+  if (!raw.startsWith("@")) return raw.replace(/^\uFEFF/, "");
+  const filePath = raw.slice(1).trim();
+  if (!filePath) {
+    throw new Error(`Invalid ${flagName} value: empty @file path.`);
+  }
+  try {
+    return readFileSync7(resolveAtFilePath(filePath), "utf8").replace(
+      /^\uFEFF/,
+      ""
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to read ${flagName} file '${filePath}': ${message}`
+    );
+  }
+}
+function invalidJsonError(flagName, message) {
+  const error = new Error(
+    `Invalid JSON in ${flagName}: ${message}`
+  );
+  error.code = "INVALID_JSON";
+  return error;
+}
+function parseJsonObjectArgument(raw, flagName) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readJsonArgument(raw, flagName));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith("Failed to read ") || message.startsWith("Invalid ")) {
+      throw error;
+    }
+    throw invalidJsonError(flagName, message);
+  }
+  if (!isRecord5(parsed)) {
+    throw invalidJsonError(flagName, "expected an object.");
+  }
+  return parsed;
+}
 function parseExecuteOptions(args) {
   const toolId = args[0];
   if (!toolId) {
@@ -15123,12 +15451,15 @@ function parseExecuteOptions(args) {
       const next = args[index + 1];
       outputFormat = "json";
       if (next && !next.startsWith("--")) {
-        Object.assign(params, JSON.parse(args[++index]));
+        Object.assign(
+          params,
+          parseJsonObjectArgument(args[++index], "--json")
+        );
       }
       continue;
     }
     if ((arg === "--input" || arg === "--payload") && args[index + 1]) {
-      Object.assign(params, JSON.parse(args[++index]));
+      Object.assign(params, parseJsonObjectArgument(args[++index], arg));
       continue;
     }
     if (arg === "--output-format" && args[index + 1]) {
@@ -15448,8 +15779,8 @@ async function executeTool(args) {
 
 // src/cli/commands/update.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync8 } from "fs";
-import { dirname as dirname9, join as join11, resolve as resolve12 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { dirname as dirname9, join as join11, resolve as resolve13 } from "path";
 function posixShellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -15468,9 +15799,9 @@ function buildSourceUpdateCommand(sourceRoot) {
   return `${cdCommand} && git fetch origin main --tags && git merge --ff-only origin/main`;
 }
 function findRepoBackedSdkRoot(startPath) {
-  let current = resolve12(startPath);
+  let current = resolve13(startPath);
   while (true) {
-    if (existsSync8(join11(current, "sdk", "package.json")) && existsSync8(join11(current, "sdk", "bin", "deepline-dev.ts"))) {
+    if (existsSync9(join11(current, "sdk", "package.json")) && existsSync9(join11(current, "sdk", "bin", "deepline-dev.ts"))) {
       return current;
     }
     const parent = dirname9(current);
@@ -15479,7 +15810,7 @@ function findRepoBackedSdkRoot(startPath) {
   }
 }
 function resolveUpdatePlan() {
-  const entrypoint = process.argv[1] ? resolve12(process.argv[1]) : "";
+  const entrypoint = process.argv[1] ? resolve13(process.argv[1]) : "";
   const sourceRoot = entrypoint ? findRepoBackedSdkRoot(dirname9(entrypoint)) : null;
   if (sourceRoot) {
     return {
@@ -15713,7 +16044,7 @@ function commandCompatibilityHint(currentFamily, commandName, baseUrl) {
     lines.push(
       "",
       "  To stay on the SDK CLI, install the SDK agent skill:",
-      `    ${skillsInstallCommand(baseUrl, "deepline-sdk")}`,
+      `    ${skillsInstallCommand(baseUrl, "deepline-plays")}`,
       "  To use the legacy Python CLI instead:",
       `    ${legacyPythonInstallCommand(baseUrl)}`,
       "  `deepline update` updates this SDK CLI, but it will not switch CLI families."
@@ -15726,7 +16057,7 @@ function commandCompatibilityHint(currentFamily, commandName, baseUrl) {
       "",
       "  To use SDK commands, install the SDK CLI and SDK agent skill:",
       `    ${sdkNpmGlobalInstallCommand()}`,
-      `    ${skillsInstallCommand(baseUrl, "deepline-sdk")}`,
+      `    ${skillsInstallCommand(baseUrl, "deepline-plays")}`,
       "  `deepline update` updates this Python CLI and its skills, but it will not switch CLI families."
     );
     if (compatibility.python_alternative) {
@@ -15744,22 +16075,39 @@ function unknownCommandNameFromMessage(message) {
 // src/cli/skills-sync.ts
 import { spawn as spawn2, spawnSync } from "child_process";
 import {
-  existsSync as existsSync9,
+  existsSync as existsSync10,
   mkdirSync as mkdirSync5,
   readdirSync as readdirSync2,
-  readFileSync as readFileSync7,
+  readFileSync as readFileSync8,
   statSync as statSync2,
   writeFileSync as writeFileSync10
 } from "fs";
 import { homedir as homedir6 } from "os";
 import { dirname as dirname10, join as join12 } from "path";
 var CHECK_TIMEOUT_MS2 = 3e3;
-var SDK_SKILL_NAME = "deepline-sdk";
+var SDK_SKILL_NAME = "deepline-plays";
 var attemptedSync = false;
 function shouldSkipSkillsSync() {
   const value = process.env.DEEPLINE_SKIP_SKILLS_SYNC?.trim().toLowerCase();
   return value === "1" || value === "true" || value === "yes" || value === "on";
 }
+function activePluginSkillsDir() {
+  const pluginMode = process.env.DEEPLINE_PLUGIN_MODE?.trim().toLowerCase();
+  if (pluginMode !== "true" && pluginMode !== "1" && pluginMode !== "yes" && pluginMode !== "on") {
+    return "";
+  }
+  const dir = process.env.DEEPLINE_PLUGIN_SKILLS_DIR?.trim() ?? "";
+  return dir && existsSync10(dir) ? dir : "";
+}
+function readPluginSkillsVersion() {
+  const dir = activePluginSkillsDir();
+  if (!dir) return "";
+  try {
+    return readFileSync8(join12(dir, ".version"), "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
 function sdkSkillsVersionPath(baseUrl) {
   const home = process.env.HOME?.trim() || homedir6();
   return join12(
@@ -15772,10 +16120,12 @@ function sdkSkillsVersionPath(baseUrl) {
   );
 }
 function readLocalSkillsVersion(baseUrl) {
+  const pluginVersion = readPluginSkillsVersion();
+  if (pluginVersion) return pluginVersion;
   const path = sdkSkillsVersionPath(baseUrl);
-  if (!existsSync9(path)) return "";
+  if (!existsSync10(path)) return "";
   try {
-    return readFileSync7(path, "utf-8").trim();
+    return readFileSync8(path, "utf-8").trim();
   } catch {
     return "";
   }
@@ -15788,7 +16138,8 @@ function writeLocalSkillsVersion(baseUrl, version) {
 }
 function installedSdkSkillHasStalePositionalExecuteExamples() {
   const home = process.env.HOME?.trim() || homedir6();
-  const roots = [
+  const pluginSkillsDir = activePluginSkillsDir();
+  const roots = pluginSkillsDir ? [join12(pluginSkillsDir, SDK_SKILL_NAME)] : [
     join12(home, ".claude", "skills", SDK_SKILL_NAME),
     join12(home, ".agents", "skills", SDK_SKILL_NAME)
   ];
@@ -15808,14 +16159,14 @@ function installedSdkSkillHasStalePositionalExecuteExamples() {
         continue;
       }
       if (!entry.endsWith(".md")) continue;
-      const text = readFileSync7(path, "utf-8");
+      const text = readFileSync8(path, "utf-8");
       if (staleMarkers.some((marker) => text.includes(marker))) return true;
     }
     return false;
   };
   for (const root of roots) {
     try {
-      if (existsSync9(root) && scan(root)) return true;
+      if (existsSync10(root) && scan(root)) return true;
     } catch {
       continue;
     }
@@ -15887,7 +16238,7 @@ function resolveSkillsInstallCommands(baseUrl) {
   return [npxInstall];
 }
 function runOneSkillsInstall(install) {
-  return new Promise((resolve13) => {
+  return new Promise((resolve14) => {
     const child = spawn2(install.command, install.args, {
       stdio: ["ignore", "ignore", "pipe"],
       env: process.env
@@ -15897,7 +16248,7 @@ function runOneSkillsInstall(install) {
       stderr += chunk.toString("utf-8");
     });
     child.on("error", (error) => {
-      resolve13({
+      resolve14({
         ok: false,
         detail: `failed to start ${install.command}: ${error.message}`,
         manualCommand: install.manualCommand
@@ -15905,11 +16256,11 @@ function runOneSkillsInstall(install) {
     });
     child.on("close", (code) => {
       if (code === 0) {
-        resolve13({ ok: true, detail: "", manualCommand: install.manualCommand });
+        resolve14({ ok: true, detail: "", manualCommand: install.manualCommand });
         return;
       }
       const detail = stderr.trim();
-      resolve13({
+      resolve14({
         ok: false,
         detail: detail ? `${install.command}: ${detail}` : `${install.command} exited ${code}`,
         manualCommand: install.manualCommand
@@ -15946,18 +16297,22 @@ function writeSdkSkillsStatusLine(line) {
 async function syncSdkSkillsIfNeeded(baseUrl) {
   if (attemptedSync || shouldSkipSkillsSync()) return;
   attemptedSync = true;
+  const usingPluginSkills = Boolean(activePluginSkillsDir());
   const localVersion = readLocalSkillsVersion(baseUrl);
   const update = await fetchSkillsUpdate(baseUrl, localVersion);
   const hasStaleInstalledSkill = installedSdkSkillHasStalePositionalExecuteExamples();
+  if (usingPluginSkills) {
+    return;
+  }
   if (!update?.needsUpdate && !hasStaleInstalledSkill || !update?.remoteVersion) {
     return;
   }
-  writeSdkSkillsStatusLine("SDK skills changed; syncing deepline-sdk skill...");
+  writeSdkSkillsStatusLine("SDK skills changed; syncing deepline-plays skill...");
   const installed = await runSkillsInstall(baseUrl);
   if (!installed) return;
   if (installedSdkSkillHasStalePositionalExecuteExamples()) {
     process.stderr.write(
-      "SDK skills sync completed, but installed deepline-sdk docs still contain stale positional ctx.tools.execute examples.\n"
+      "SDK skills sync completed, but installed deepline-plays docs still contain stale positional ctx.tools.execute examples.\n"
     );
     return;
   }