deepline 0.1.48 → 0.1.49

package/dist/cli/index.mjs

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { Command as Command2 } from "commander";
+import { mkdtemp, rm, writeFile as writeFile4 } from "fs/promises";
+import { join as join11 } from "path";
+import { tmpdir as tmpdir4 } from "os";
+import { Command as Command3 } from "commander";
 
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -193,7 +196,7 @@ function resolveConfig(options) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.48";
+var SDK_VERSION = "0.1.49";
 var SDK_API_CONTRACT = "2026-05-stripe-promo-checkout";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
@@ -713,9 +716,18 @@ var DeeplineClient = class {
    * console.log(`Found ${searchTools.length} search tools`);
    * ```
    */
-  async listTools() {
+  async listTools(options) {
+    const params = new URLSearchParams();
+    if (options?.categories?.trim()) {
+      params.set("categories", options.categories.trim());
+    }
+    if (options?.grep?.trim()) {
+      params.set("grep", options.grep.trim());
+      params.set("grep_mode", options.grepMode ?? "all");
+    }
+    const suffix = params.toString() ? `?${params.toString()}` : "";
     const res = await this.http.get(
-      "/api/v2/tools"
+      `/api/v2/tools${suffix}`
     );
     return res.tools;
   }
@@ -1350,9 +1362,17 @@ var DeeplineClient = class {
       options?.reason ? { reason: options.reason } : {}
     );
   }
-  async listPlays() {
+  async listPlays(options) {
+    const params = new URLSearchParams();
+    if (options?.origin) params.set("origin", options.origin);
+    if (options?.grep?.trim()) {
+      params.set("grep", options.grep.trim());
+      params.set("grep_mode", options.grepMode ?? "all");
+      params.set("limit", "60");
+    }
+    const suffix = params.toString() ? `?${params.toString()}` : "";
     const response = await this.http.get(
-      "/api/v2/plays"
+      `/api/v2/plays${suffix}`
     );
     return response.plays ?? [];
   }
@@ -5670,6 +5690,16 @@ function extractPlayName(code, filePath) {
 function isFileTarget(target) {
   return existsSync6(resolve9(target));
 }
+function looksLikeRunId(target) {
+  return /^play\/[^/]+\/run\/[^/]+/.test(target.trim());
+}
+function formatPlayCommandReceivedRunIdError(input) {
+  return `\`deepline plays ${input.command} <run-id>\` expects a play name, but this looks like a run id.
+Use:
+  deepline runs get ${input.runId} --json
+  deepline runs logs ${input.runId} --json
+  deepline runs export ${input.runId} --out output.csv`;
+}
 function looksLikeFilePath(target) {
   if (target.trim().toLowerCase().startsWith("prebuilt/")) {
     return false;
@@ -6096,6 +6126,69 @@ function describeLiveEventPhase(event) {
   }
   return null;
 }
+function formatProgressLabel(raw) {
+  const value = typeof raw === "string" && raw.trim() ? raw.trim() : "step";
+  return value.replace(/^map:/, "").replace(/^tool:/, "");
+}
+function formatProgressCounts(input) {
+  const completed = typeof input.completed === "number" && Number.isFinite(input.completed) ? input.completed : null;
+  const total = typeof input.total === "number" && Number.isFinite(input.total) ? input.total : null;
+  if (completed === null || total === null || total <= 0) {
+    return null;
+  }
+  const percent = Math.max(0, Math.min(100, Math.round(completed / total * 100)));
+  const failed = typeof input.failed === "number" && Number.isFinite(input.failed) && input.failed > 0 ? `, failed ${formatInteger(input.failed)}` : "";
+  return `${formatInteger(completed)}/${formatInteger(total)} (${percent}%)${failed}`;
+}
+function getProgressLinesFromLiveEvent(event) {
+  const payload = getEventPayload(event);
+  if (event.type === "play.step.progress") {
+    const counts = formatProgressCounts({
+      completed: payload.completed,
+      total: payload.total,
+      failed: payload.failed
+    });
+    if (!counts) return [];
+    return [`progress ${formatProgressLabel(payload.stepId)}: ${counts}`];
+  }
+  if (event.type !== "play.run.snapshot" && event.type !== "play.run.final_status") {
+    return [];
+  }
+  const nodeStates = Array.isArray(payload.nodeStates) ? payload.nodeStates : Array.isArray(payload.steps) ? payload.steps : [];
+  const lines = [];
+  for (const state of nodeStates) {
+    if (!state || typeof state !== "object" || Array.isArray(state)) {
+      continue;
+    }
+    const record = state;
+    const progress = record.progress && typeof record.progress === "object" && !Array.isArray(record.progress) ? record.progress : null;
+    if (!progress) {
+      continue;
+    }
+    const counts = formatProgressCounts({
+      completed: progress.completed,
+      total: progress.total,
+      failed: progress.failed
+    });
+    if (!counts) {
+      continue;
+    }
+    lines.push(
+      `progress ${formatProgressLabel(record.nodeId ?? progress.artifactTableNamespace)}: ${counts}`
+    );
+  }
+  return lines;
+}
+function printPlayProgressLines(input) {
+  for (const line of input.lines) {
+    const signature = line.trim();
+    if (!signature || input.state.lastProgressSignature === signature) {
+      continue;
+    }
+    input.state.lastProgressSignature = signature;
+    input.progress.writeLine(line);
+  }
+}
 function buildPlayDashboardUrl(baseUrl, playName) {
   const trimmedBase = baseUrl.replace(/\/$/, "");
   const encodedPlayName = encodeURIComponent(playName);
@@ -6169,6 +6262,13 @@ async function waitForPlayCompletionByStream(input) {
         state: input.state,
         progress: input.progress
       });
+      if (!input.jsonOutput) {
+        printPlayProgressLines({
+          lines: getProgressLinesFromLiveEvent(event),
+          state: input.state,
+          progress: input.progress
+        });
+      }
       const status = getStatusFromLiveEvent(event);
       if (status && TERMINAL_PLAY_STATUSES2.has(status)) {
         const finalStatus = await input.client.getPlayStatus(input.workflowId, {
@@ -6237,7 +6337,8 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
   );
   const state = {
     lastLogIndex: 0,
-    emittedRunnerStarted: false
+    emittedRunnerStarted: false,
+    lastProgressSignature: null
   };
   const controller = new AbortController();
   let timedOut = false;
@@ -6265,11 +6366,6 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
       }
       const workflowId = lastKnownWorkflowId || "pending";
       if (workflowId !== "pending" && !emittedDashboardUrl) {
-        openPlayDashboard({
-          dashboardUrl,
-          jsonOutput: input.jsonOutput,
-          noOpen: input.noOpen
-        });
         if (!input.jsonOutput) {
           writeStartedPlayRun({
             runId: workflowId,
@@ -6279,6 +6375,11 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
             progress: input.progress
           });
         }
+        openPlayDashboard({
+          dashboardUrl,
+          jsonOutput: input.jsonOutput,
+          noOpen: input.noOpen
+        });
         input.progress.phase(`loading play on ${dashboardUrl}`);
         emittedDashboardUrl = true;
       }
@@ -6301,6 +6402,13 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
         state,
         progress: input.progress
       });
+      if (!input.jsonOutput) {
+        printPlayProgressLines({
+          lines: getProgressLinesFromLiveEvent(event),
+          state,
+          progress: input.progress
+        });
+      }
       const finalStatus = getFinalStatusFromLiveEvent(event);
       if (finalStatus) {
         recordCliTrace({
@@ -6569,6 +6677,7 @@ function buildRunNextCommands(status) {
   const commands = {
     get: `deepline runs get ${runId} --json`,
     full: `deepline runs get ${runId} --full --json`,
+    export: `deepline runs export ${runId} --out output.csv`,
     stop: `deepline runs stop ${runId} --reason "stale lock" --json`,
     logs: `deepline runs logs ${runId} --out run.log --json`
   };
@@ -6701,6 +6810,32 @@ function formatInsufficientCreditsMessage(input) {
   const addSuffix = billingUrl && recommended !== "-" ? ` Add >=${recommended} at ${billingUrl}.` : billingUrl ? ` Add credits at ${billingUrl}.` : "";
   return `Workspace balance ${balance} < required ${required} for ${operation}${workspaceSuffix}.${addSuffix}`;
 }
+function buildInsufficientCreditsSummaryLines(input) {
+  const progress = input.status.progress;
+  const rowsInfo = extractCanonicalRowsInfo(input.status);
+  const completed = getNumericField(progress, "completed") ?? getNumericField(progress, "completedRows") ?? rowsInfo?.rows.length ?? null;
+  const total = getNumericField(progress, "total") ?? getNumericField(progress, "totalRows") ?? rowsInfo?.totalRows ?? null;
+  const lines = [
+    "  status: stopped_insufficient_credits",
+    completed === null ? "  completed rows: unknown" : `  completed rows: ${formatInteger(completed)}${total !== null ? ` of ${formatInteger(total)}` : ""}`,
+    "  reusable receipts: yes; rerun after adding credits to continue from completed provider work"
+  ];
+  const billingUrl = getStringField(input.billing, "billing_url");
+  const recommended = formatCreditAmount(
+    input.billing.recommended_add_credits ?? input.billing.needed_credits
+  );
+  if (billingUrl) {
+    lines.push(
+      recommended !== "-" ? `  add credits: add >=${recommended} at ${billingUrl}` : `  add credits: ${billingUrl}`
+    );
+  }
+  const runId = input.status.runId?.trim();
+  if (runId) {
+    lines.push(`  inspect: deepline runs get ${runId} --json`);
+    lines.push(`  export partial: deepline runs export ${runId} --out output.csv`);
+  }
+  return lines;
+}
 function formatPlayErrorForDisplay(status, error) {
   if (!error) {
     return null;
@@ -6891,6 +7026,19 @@ function formatDatasetStatsLines(datasetStats) {
   }
   return lines;
 }
+function buildJsonRunResultRenderLines(status) {
+  const publicStatus = status.status ?? "running";
+  const runId = status.runId ?? "unknown";
+  const lines = [`${publicStatus}  ${runId}`];
+  const progressError = status.progress?.error;
+  if (typeof progressError === "string") {
+    const billing = extractBillingForStatus(status, progressError);
+    if (isInsufficientCreditsBilling(billing)) {
+      lines.push(...buildInsufficientCreditsSummaryLines({ status, billing }));
+    }
+  }
+  return lines;
+}
 function writePlayResult(status, jsonOutput, options) {
   if (jsonOutput) {
     const payload2 = options?.fullJson ? enrichPlayStatusWithDatasetStats(status) : compactPlayStatus(status);
@@ -6900,9 +7048,7 @@ function writePlayResult(status, jsonOutput, options) {
         sections: [
           {
             title: "run result",
-            lines: [
-              `${status.status ?? "running"}  ${status.runId ?? "unknown"}`
-            ]
+            lines: buildJsonRunResultRenderLines(status)
           }
         ]
       }
@@ -6929,6 +7075,10 @@ function writePlayResult(status, jsonOutput, options) {
   lines.push(...formatDatasetStatsLines(datasetStats));
   const progressError = status.progress?.error;
   if (progressError && typeof progressError === "string") {
+    const billing = extractBillingForStatus(status, progressError);
+    if (isInsufficientCreditsBilling(billing)) {
+      lines.push(...buildInsufficientCreditsSummaryLines({ status, billing }));
+    }
     const displayError = formatPlayErrorForDisplay(status, progressError) ?? progressError;
     lines.push(`  error: ${displayError.slice(0, 200)}`);
   }
@@ -7308,24 +7458,31 @@ function writeStartedPlayRun(input) {
     workflowId: input.runId,
     name: input.playName,
     status: input.status ?? "started",
-    dashboardUrl: input.dashboardUrl
+    dashboardUrl: input.dashboardUrl,
+    next: {
+      inspect: `deepline runs get ${input.runId} --json`,
+      full: `deepline runs get ${input.runId} --full --json`,
+      logs: `deepline runs logs ${input.runId} --json`,
+      export: `deepline runs export ${input.runId} --out output.csv`,
+      stop: `deepline runs stop ${input.runId} --reason "stale lock" --json`
+    }
   };
+  const lines = [
+    `Started ${input.playName}`,
+    `  run id: ${input.runId}`,
+    `  inspect: deepline runs get ${input.runId} --json`,
+    `  full debug: deepline runs get ${input.runId} --full --json`,
+    `  logs: deepline runs logs ${input.runId} --json`,
+    `  export after completion: deepline runs export ${input.runId} --out output.csv`,
+    `  stop run: deepline runs stop ${input.runId} --reason "stale lock" --json`
+  ];
   if (input.jsonOutput) {
     printCommandEnvelope({
       ...payload,
-      render: { sections: [{ title: "play run", lines: [`Started ${input.playName}`, `run id: ${input.runId}`] }] }
+      render: { sections: [{ title: "play run", lines }] }
     }, { json: true });
     return;
   }
-  const lines = [
-    `Started ${input.playName}`,
-    `  run id: ${input.runId}`,
-    `  get status: deepline runs get ${input.runId} --json`,
-    `  logs: deepline runs logs ${input.runId} --json`,
-    `  stop run: deepline runs stop ${input.runId} --reason "stale lock" --json`,
-    `  result JSON: deepline runs get ${input.runId} --json`,
-    `  full debug JSON: deepline runs get ${input.runId} --full --json`
-  ];
   if (input.dashboardUrl) {
     lines.push(`  play page: ${input.dashboardUrl}`);
   }
@@ -7341,13 +7498,13 @@ function writeStartedPlayRun(input) {
 ` });
 }
 function parsePlayRunOptions(args) {
-  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--watch] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--watch] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--watch] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--watch] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--<input> value]\n       Unknown --<input> value flags, such as --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.map guidance.";
+  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--<input> value]\n       Unknown --<input> value flags, such as --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.map guidance.";
   let filePath = null;
   let playName = null;
   let input = null;
   let revisionId = null;
   let revisionSelector = null;
-  const watch = args.includes("--watch") || args.includes("--wait");
+  const watch = !args.includes("--no-wait");
   let jsonOutput = watch ? args.includes("--json") : argsWantJson(args);
   const emitLogs = !jsonOutput || args.includes("--logs");
   const force = args.includes("--force");
@@ -7393,7 +7550,7 @@ function parsePlayRunOptions(args) {
       waitTimeoutMs = parsePositiveInteger2(args[++index], arg);
       continue;
     }
-    if (arg === "--json" || arg === "--wait" || arg === "--tail" || arg === "--watch" || arg === "--logs" || arg === "--force" || arg === "--no-open") {
+    if (arg === "--json" || arg === "--wait" || arg === "--tail" || arg === "--watch" || arg === "--no-wait" || arg === "--logs" || arg === "--force" || arg === "--no-open") {
       if (arg === "--watch") {
         continue;
       }
@@ -8249,6 +8406,12 @@ async function handlePlayGet(args) {
     console.error("Usage: deepline play get <play-file.ts|play-name> [--json]");
     return 1;
   }
+  if (looksLikeRunId(target)) {
+    console.error(
+      formatPlayCommandReceivedRunIdError({ command: "get", runId: target })
+    );
+    return 2;
+  }
   const client = new DeeplineClient();
   const explicitJson = args.includes("--json");
   const sourceOutput = args.includes("--source");
@@ -8363,8 +8526,20 @@ async function handlePlayVersions(args) {
 }
 async function handlePlayList(args) {
   const jsonOutput = argsWantJson(args);
+  const originArgIndex = args.findIndex((arg) => arg === "--origin");
+  const rawOrigin = originArgIndex >= 0 ? args[originArgIndex + 1] : void 0;
+  if (rawOrigin && rawOrigin !== "prebuilt" && rawOrigin !== "owned") {
+    throw new Error(`Invalid value for --origin: ${rawOrigin}`);
+  }
+  const origin = rawOrigin;
   const client = new DeeplineClient();
-  const plays = await client.listPlays();
+  const plays = (await client.listPlays({
+    ...origin ? { origin } : {}
+  })).filter((play) => {
+    if (!origin) return true;
+    const isPrebuilt = play.origin === "prebuilt" || play.ownerType === "deepline";
+    return origin === "prebuilt" ? isPrebuilt : !isPrebuilt;
+  });
   if (jsonOutput) {
     process.stdout.write(`${JSON.stringify(plays)}
 `);
@@ -8467,6 +8642,54 @@ function printPlayDescription(play) {
     );
   }
 }
+function compactPlaySchema(schema) {
+  if (!schema) return null;
+  const fields = Array.isArray(schema.fields) ? schema.fields.map(
+    (field) => field && typeof field === "object" ? {
+      name: String(field.name ?? ""),
+      type: field.type ?? void 0,
+      required: field.required ?? void 0
+    } : null
+  ).filter((field) => Boolean(field?.name)) : [];
+  return fields.length > 0 ? { fields } : schema;
+}
+function playSchemaMetadata(schema, key) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return null;
+  const value = schema[key];
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function playRunCommand(play, options) {
+  const target = play.reference || play.name;
+  if (options?.csvInput) {
+    const inputField = typeof options.csvInput.inputField === "string" && options.csvInput.inputField.trim() ? options.csvInput.inputField.trim() : "csv";
+    return `deepline plays run ${target} --input '${JSON.stringify({ [inputField]: "leads.csv" })}' --watch`;
+  }
+  return `deepline plays run ${target} --input '{...}' --watch`;
+}
+function summarizePlayListItemForCli(play, options) {
+  const aliases = play.aliases?.length ? play.aliases : [play.name];
+  const csvInput = playSchemaMetadata(play.inputSchema, "csvInput");
+  const rowOutputSchema = playSchemaMetadata(play.outputSchema, "rowOutputSchema");
+  const runCommand2 = playRunCommand(play, { csvInput });
+  return {
+    name: play.name,
+    ...play.reference ? { reference: play.reference } : {},
+    ...play.displayName ? { displayName: play.displayName } : {},
+    origin: play.origin,
+    ownerType: play.ownerType,
+    canEdit: play.canEdit,
+    canClone: play.canClone,
+    aliases,
+    inputSchema: options?.compact ? compactPlaySchema(play.inputSchema) : play.inputSchema ?? null,
+    outputSchema: options?.compact ? compactPlaySchema(play.outputSchema) : play.outputSchema ?? null,
+    ...csvInput ? { csvInput } : {},
+    ...rowOutputSchema ? { rowOutputSchema } : {},
+    runCommand: runCommand2,
+    examples: [runCommand2],
+    currentPublishedVersion: play.currentPublishedVersion ?? null,
+    isDraftDirty: play.isDraftDirty
+  };
+}
 async function handlePlaySearch(args) {
   let options;
   try {
@@ -8488,6 +8711,100 @@ async function handlePlaySearch(args) {
   }
   process.stdout.write(`${plays.length} plays found:
 
+`);
+  for (const play of plays) {
+    printPlayDescription(play);
+    console.log("");
+  }
+  return 0;
+}
+function normalizePlayGrepText(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value.toLowerCase();
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value).toLowerCase();
+  }
+  if (Array.isArray(value)) return value.map(normalizePlayGrepText).join(" ");
+  if (typeof value === "object") {
+    return Object.values(value).map(normalizePlayGrepText).join(" ");
+  }
+  return "";
+}
+function parsePlayGrepTerms(query, mode) {
+  const trimmed = query.trim().toLowerCase();
+  if (!trimmed) return [];
+  if (mode === "phrase") return [trimmed];
+  const matches = trimmed.match(/"([^"]+)"|'([^']+)'|\S+/g) ?? [];
+  return matches.map((term) => term.replace(/^["']|["']$/g, "").trim()).filter(Boolean);
+}
+function matchesPlayGrepQuery(value, query, mode) {
+  const terms = parsePlayGrepTerms(query, mode);
+  if (terms.length === 0) return true;
+  const haystack = normalizePlayGrepText(value);
+  if (mode === "any") return terms.some((term) => haystack.includes(term));
+  return terms.every((term) => haystack.includes(term));
+}
+async function handlePlayGrep(args) {
+  const query = args[0]?.trim();
+  if (!query) {
+    console.error("Usage: deepline plays grep <query> [--origin prebuilt|owned] [--compact] [--json]");
+    return 1;
+  }
+  let origin;
+  let mode = "all";
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--origin" && args[index + 1]) {
+      const rawOrigin = args[++index].trim().toLowerCase();
+      if (rawOrigin !== "prebuilt" && rawOrigin !== "owned") {
+        throw new Error(`Invalid value for --origin: ${rawOrigin}`);
+      }
+      origin = rawOrigin;
+    }
+    if (arg === "--mode" && args[index + 1]) {
+      const rawMode = args[++index].trim().toLowerCase();
+      mode = rawMode === "any" || rawMode === "phrase" ? rawMode : "all";
+    }
+  }
+  const compact = args.includes("--compact");
+  const client = new DeeplineClient();
+  const plays = (await client.listPlays({
+    grep: query,
+    grepMode: mode,
+    ...origin ? { origin } : {}
+  })).filter((play) => {
+    if (!origin) return true;
+    const isPrebuilt = play.origin === "prebuilt" || play.ownerType === "deepline";
+    return origin === "prebuilt" ? isPrebuilt : !isPrebuilt;
+  }).filter(
+    (play) => matchesPlayGrepQuery(
+      {
+        name: play.name,
+        reference: play.reference,
+        displayName: play.displayName,
+        origin: play.origin,
+        ownerType: play.ownerType,
+        aliases: play.aliases,
+        inputSchema: play.inputSchema,
+        outputSchema: play.outputSchema
+      },
+      query,
+      mode
+    )
+  ).map((play) => summarizePlayListItemForCli(play, { compact }));
+  if (argsWantJson(args)) {
+    process.stdout.write(`${JSON.stringify({
+      plays,
+      count: plays.length,
+      query,
+      grep: { mode, terms: parsePlayGrepTerms(query, mode) },
+      filters: { origin: origin ?? null }
+    })}
+`);
+    return 0;
+  }
+  process.stdout.write(`${plays.length} plays found:
+
 `);
   for (const play of plays) {
     printPlayDescription(play);
@@ -8503,6 +8820,15 @@ async function handlePlayDescribe(args) {
     );
     return 1;
   }
+  if (looksLikeRunId(playName)) {
+    console.error(
+      formatPlayCommandReceivedRunIdError({
+        command: "describe",
+        runId: playName
+      })
+    );
+    return 2;
+  }
   const client = new DeeplineClient();
   await assertCanonicalNamedPlayReference(client, playName);
   const play = await client.describePlay(
@@ -8659,7 +8985,7 @@ Common commands:
   deepline plays search email --json
   deepline plays describe person-linkedin-to-email --json
   deepline plays check my.play.ts
-  deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
+  deepline plays run my.play.ts --input '{"domain":"stripe.com"}'
   deepline plays set-live my.play.ts --json
   deepline plays get person-linkedin-to-email --json
 `
@@ -8690,8 +9016,10 @@ Notes:
   Unknown --foo value and --foo.bar value flags are passed into play input.
   Example: --limit 5 becomes input.limit = 5.
   File args accept local paths; the CLI stages files before submit.
-  --watch prints logs, previews, stats, and next commands.
-  --wait is accepted as a compatibility alias for --watch.
+  By default, run waits for completion and prints logs, previews, stats, and
+  next commands. --watch and --wait are accepted compatibility aliases for the
+  default behavior. Use --no-wait only when you intentionally want
+  a fire-and-forget run id.
   The play page opens in your browser as soon as the run starts; use --no-open
   to only print the URL.
   --force supersedes active runs; it does not bypass completed reuse.
@@ -8719,17 +9047,18 @@ Idempotent execution:
     .run({ key: 'domain', staleAfterSeconds: 86400 })
 
 Examples:
-  deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
-  deepline plays run my.play.ts --input @input.json --wait --json
-  deepline plays run person-linkedin-to-email --input '{"linkedin_url":"..."}' --watch
-  deepline plays run cto-search.play.ts --limit 5 --watch
+  deepline plays run my.play.ts --input '{"domain":"stripe.com"}'
+  deepline plays run my.play.ts --input @input.json --json
+  deepline plays run person-linkedin-to-email --input '{"linkedin_url":"..."}'
+  deepline plays run cto-search.play.ts --limit 5
+  deepline plays run long-background-play --no-wait
   deepline runs export <run-id> --out output.csv
   deepline runs get <run-id>
 `
   ).option("--file <path>", "Local play file to run").option("--name <name>", "Saved play name to run").option("-i, --input <json>", "Input JSON object or @file path").option("--live", "Run the current live revision explicitly").option("--latest", "Run the newest saved revision, even if it is not live").option(
     "--revision-id <id>",
     "Run a specific saved revision instead of the live revision"
-  ).option("--watch", "Stream logs until completion").option("--wait", "Alias for --watch; stream logs until completion").option(
+  ).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(
     "--logs",
     "When output is non-interactive, stream play logs to stderr while waiting"
   ).option("--tail-timeout-ms <ms>", "Timeout while watching the run stream").option("--force", "Supersede any active runs for this play").option("--no-open", "Print the play page URL without opening a browser").option("--json", "Emit JSON output").addHelpText(
@@ -8762,6 +9091,7 @@ Pass-through input flags:
       ...options.live ? ["--live"] : [],
       ...options.latest ? ["--latest"] : [],
       ...options.revisionId ? ["--revision-id", options.revisionId] : [],
+      ...options.wait === false ? ["--no-wait"] : [],
       ...options.watch || options.wait ? ["--watch"] : [],
       ...options.logs ? ["--logs"] : [],
       ...options.tailTimeoutMs ? ["--tail-timeout-ms", options.tailTimeoutMs] : [],
@@ -8802,24 +9132,27 @@ Notes:
 
 Examples:
   deepline plays list
-  deepline plays list --json
+  deepline plays list --origin prebuilt --json
   deepline plays search email --origin prebuilt --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  ).option("--origin <origin>", "Filter to prebuilt or owned plays").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handlePlayList([
+      ...options.origin ? ["--origin", options.origin] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("search <query>").description("Search saved and prebuilt plays.").addHelpText(
+  const addPlaySearchCommand = (command) => command.description("Search saved and prebuilt plays.").addHelpText(
     "after",
     `
 Notes:
   Ranked discovery for workflows. Use --origin prebuilt or --origin owned when
   you need to narrow results. Use describe on a result before running it.
+  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 "linkedin to email" --origin prebuilt --compact --json
+  deepline plays grep "linkedin to email" --origin prebuilt --compact --json
   deepline plays describe person-linkedin-to-email --json
 `
   ).option("--origin <origin>", "Filter to prebuilt or owned plays").option("--compact", "Emit compact schemas").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
@@ -8830,6 +9163,30 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
+  addPlaySearchCommand(play.command("search <query>"));
+  play.command("grep <query>").description("Literal grep over play names, aliases, schemas, and descriptions.").addHelpText(
+    "after",
+    `
+Notes:
+  Literal registry filtering. Terms are matched case-insensitively against play
+  names, references, display names, aliases, ownership, and schemas. Use
+  --mode phrase for exact phrase matching, --mode any for OR, and the default
+  --mode all for AND.
+
+Examples:
+  deepline plays grep email --origin prebuilt --json
+  deepline plays grep "company contact" --origin prebuilt --mode all --json
+  deepline plays describe prebuilt/company-to-contact --json
+`
+  ).option("--origin <origin>", "Filter to prebuilt or owned plays").option("--compact", "Emit compact schemas").option("--mode <mode>", "Grep matching mode: all, any, or phrase").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+    process.exitCode = await handlePlayGrep([
+      query,
+      ...options.origin ? ["--origin", options.origin] : [],
+      ...options.compact ? ["--compact"] : [],
+      ...options.mode ? ["--mode", options.mode] : [],
+      ...options.json ? ["--json"] : []
+    ]);
+  });
   play.command("describe <target>").description("Describe a play contract and how to run it.").addHelpText(
     "after",
     `
@@ -8858,7 +9215,7 @@ Notes:
 Examples:
   deepline plays versions --name my-play
   deepline plays versions --name my-play --json
-  deepline plays run my-play --revision-id <revision-id> --watch
+  deepline plays run my-play --revision-id <revision-id>
 `
   ).option("--name <name>", "Saved play name").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handlePlayVersions([
@@ -9060,6 +9417,7 @@ Examples:
 }
 
 // src/cli/commands/tools.ts
+import { Option } from "commander";
 import { chmodSync, mkdtempSync, writeFileSync as writeFileSync8 } from "fs";
 import { tmpdir as tmpdir3 } from "os";
 import { join as join8 } from "path";
@@ -9244,9 +9602,42 @@ function toListedTool(tool) {
     executeCommand: `deepline tools execute ${tool.toolId}`
   };
 }
+function normalizeGrepText(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value.toLowerCase();
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value).toLowerCase();
+  }
+  if (Array.isArray(value)) return value.map(normalizeGrepText).join(" ");
+  if (typeof value === "object") {
+    return Object.values(value).map(normalizeGrepText).join(" ");
+  }
+  return "";
+}
+function parseGrepTerms(query, mode) {
+  const trimmed = query.trim().toLowerCase();
+  if (!trimmed) return [];
+  if (mode === "phrase") return [trimmed];
+  const matches = trimmed.match(/"([^"]+)"|'([^']+)'|\S+/g) ?? [];
+  return matches.map((term) => term.replace(/^["']|["']$/g, "").trim()).filter(Boolean);
+}
+function matchesGrepQuery(value, query, mode) {
+  const terms = parseGrepTerms(query, mode);
+  if (terms.length === 0) return true;
+  const haystack = normalizeGrepText(value);
+  if (mode === "any") return terms.some((term) => haystack.includes(term));
+  return terms.every((term) => haystack.includes(term));
+}
 async function listTools(args) {
   const client = new DeeplineClient();
-  const items = (await client.listTools()).map(toListedTool);
+  const categoryArgIndex = args.findIndex((arg) => arg === "--categories");
+  const categoryFilter = categoryArgIndex >= 0 ? args[categoryArgIndex + 1] : "";
+  const requestedCategories = categoryFilter ? categoryFilter.split(",").map((item) => item.trim()).filter(Boolean) : [];
+  const items = (await client.listTools({
+    ...categoryFilter ? { categories: categoryFilter } : {}
+  })).map(toListedTool).filter(
+    (item) => requestedCategories.length === 0 || requestedCategories.some((category) => item.categories.includes(category))
+  );
   const render = {
     sections: [
       {
@@ -9269,6 +9660,9 @@ async function listTools(args) {
     {
       tools: items,
       count: items.length,
+      filters: {
+        categories: requestedCategories
+      },
       commandTemplates: TOOL_COMMAND_TEMPLATES,
       render
     },
@@ -9295,6 +9689,56 @@ async function searchTools(queryInput, options = {}) {
   });
   return 0;
 }
+async function grepTools(queryInput, options = {}) {
+  const query = queryInput.trim();
+  if (!query) {
+    console.error("Usage: deepline tools grep <query> [--json]");
+    return 1;
+  }
+  const client = new DeeplineClient();
+  const requestedCategories = options.categories ? options.categories.split(",").map((item) => item.trim()).filter(Boolean) : [];
+  const mode = options.mode ?? "all";
+  const tools = (await client.listTools({
+    grep: query,
+    grepMode: mode,
+    ...options.categories ? { categories: options.categories } : {}
+  })).map(toListedTool).filter(
+    (item) => requestedCategories.length === 0 || requestedCategories.some((category) => item.categories.includes(category))
+  ).filter(
+    (item) => matchesGrepQuery(
+      {
+        id: item.toolId,
+        toolId: item.toolId,
+        provider: item.provider,
+        displayName: item.displayName,
+        description: item.description,
+        categories: item.categories,
+        operation: item.operation,
+        operationAliases: item.operationAliases,
+        inputFields: item.inputFields
+      },
+      query,
+      mode
+    )
+  );
+  printCommandEnvelope(
+    {
+      tools,
+      count: tools.length,
+      query,
+      grep: {
+        mode,
+        terms: parseGrepTerms(query, mode)
+      },
+      filters: {
+        categories: requestedCategories
+      },
+      commandTemplates: TOOL_COMMAND_TEMPLATES
+    },
+    { json: options.json || shouldEmitJson() }
+  );
+  return 0;
+}
 function playIdentifiers(play) {
   return [play.name, play.reference, ...play.aliases ?? []].filter((value) => Boolean(value?.trim())).map((value) => value.trim());
 }
@@ -9364,24 +9808,27 @@ Notes:
 
 Examples:
   deepline tools list
-  deepline tools list --json
+  deepline tools list --categories email_finder --json
   deepline tools search email --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  ).option("--categories <categories>", "Comma-separated categories to filter inventory").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await listTools([
+      ...options.categories ? ["--categories", options.categories] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
-  tools.command("search <query>").description("Search available tools.").addHelpText(
+  const addToolSearchCommand = (command) => command.description("Search available tools.").addHelpText(
     "after",
     `
 Notes:
   Ranked discovery for atomic provider/API operations. Results include tool ids
   that can be passed to deepline tools describe or deepline tools execute.
+  The grep alias is the same ranked retrieval surface with a more literal name
+  for agents that are filtering a registry rather than choosing a workflow.
 
 Examples:
   deepline tools search email
-  deepline tools search "company enrichment" --categories enrichment --json
+  deepline tools grep "company enrichment" --categories enrichment --json
   deepline tools search verifier --search-mode v2 --json
 `
   ).option("--categories <categories>", "Comma-separated categories to filter ranked search").option("--search_terms <terms>", "Structured search terms for ranked search").option("--search-terms <terms>", "Structured search terms for ranked search").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
@@ -9393,24 +9840,55 @@ Examples:
       includeSearchDebug: Boolean(options.includeSearchDebug)
     });
   });
+  addToolSearchCommand(tools.command("search <query>"));
+  tools.command("grep <query>").description("Literal grep over tool ids, descriptions, categories, and input fields.").addHelpText(
+    "after",
+    `
+Notes:
+  Literal registry filtering. Terms are matched case-insensitively against tool
+  ids, provider, display name, description, categories, aliases, and input
+  fields. Use --mode phrase for exact phrase matching, --mode any for OR, and
+  the default --mode all for AND.
+
+Examples:
+  deepline tools grep email --categories email_finder --json
+  deepline tools grep "phone validate" --mode all --json
+  deepline tools grep hunter --mode phrase --json
+`
+  ).option("--categories <categories>", "Comma-separated categories to filter inventory").option("--mode <mode>", "Grep matching mode: all, any, or phrase").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+    const mode = options.mode === "any" || options.mode === "phrase" ? options.mode : "all";
+    process.exitCode = await grepTools(query, {
+      json: options.json,
+      categories: options.categories,
+      mode
+    });
+  });
   const addToolMetadataCommand = (command) => command.description("Show metadata for a tool.").addHelpText(
     "after",
     `
 Notes:
-  Shows the tool contract, input schema, output schema, Deepline cost, aliases,
-  and metadata. describe is the supported discovery verb. get is removed in
-  the V2 SDK CLI; use describe for the same metadata surface.
+  Shows the compact agent contract by default: what the tool does, cost,
+  required inputs, play getters, and a runnable ctx.tools.execute snippet.
+  Use --json for the full metadata/debug payload.
 
 Examples:
   deepline tools describe hunter_email_verifier
-  deepline tools describe hunter_email_verifier --json | jq '.inputSchema'
+  deepline tools describe hunter_email_verifier --pricing-only
+  deepline tools describe hunter_email_verifier --schema-only
+  deepline tools describe hunter_email_verifier --examples-only
+  deepline tools describe hunter_email_verifier --json
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (toolId, options) => {
-    process.exitCode = await getTool([
-      toolId,
-      ...options.json ? ["--json"] : []
-    ]);
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--pricing-only", "Only print pricing and billing semantics").option("--schema-only", "Only print input schema fields").option("--examples-only", "Only print runnable examples and sample payloads").option("--getters-only", "Only print extracted list/value getters").addOption(new Option("--compact", "Compatibility alias for the default compact view").hideHelp()).addOption(new Option("--contract-json", "Compatibility alias for compact contract JSON").hideHelp()).action(async (toolId, options) => {
+    process.exitCode = await getTool(toolId, {
+      json: Boolean(options.json),
+      compact: Boolean(options.compact),
+      contractJson: Boolean(options.contractJson),
+      pricingOnly: Boolean(options.pricingOnly),
+      schemaOnly: Boolean(options.schemaOnly),
+      examplesOnly: Boolean(options.examplesOnly),
+      gettersOnly: Boolean(options.gettersOnly)
+    });
   });
   addToolMetadataCommand(tools.command("describe <toolId>"));
   tools.command("get <toolId>").description("Deprecated. Use tools describe.").addHelpText(
@@ -9463,8 +9941,7 @@ Examples:
     process.exitCode = await executeTool(args);
   });
 }
-async function getTool(args) {
-  const toolId = args[0];
+async function getTool(toolId, options = {}) {
   if (!toolId) {
     console.error("Usage: deepline tools get <toolId> [--json]");
     return 1;
@@ -9481,14 +9958,264 @@ async function getTool(args) {
     }
     throw error;
   }
-  if (argsWantJson(args)) {
+  if (options.contractJson) {
+    process.stdout.write(`${JSON.stringify(toolContractJsonForDescribe(tool, toolId))}
+`);
+    return 0;
+  }
+  const emitJson = options.json === true;
+  if (emitJson) {
     process.stdout.write(`${JSON.stringify(toolMetadataJsonForDescribe(tool, toolId))}
 `);
     return 0;
   }
-  printToolDetails(tool, toolId);
+  const onlyModes = [
+    options.pricingOnly,
+    options.schemaOnly,
+    options.examplesOnly,
+    options.gettersOnly
+  ].filter(Boolean).length;
+  if (onlyModes > 1) {
+    console.error("Use only one of --pricing-only, --schema-only, --examples-only, or --getters-only.");
+    return 2;
+  }
+  if (options.pricingOnly) {
+    printToolPricingOnly(tool, toolId);
+    return 0;
+  }
+  if (options.schemaOnly) {
+    printToolSchemaOnly(tool, toolId);
+    return 0;
+  }
+  if (options.examplesOnly) {
+    printToolExamplesOnly(tool, toolId);
+    return 0;
+  }
+  if (options.gettersOnly) {
+    printToolGettersOnly(tool, toolId);
+    return 0;
+  }
+  if (options.compact) {
+    printCompactToolContract(tool, toolId);
+    return 0;
+  }
+  if (shouldEmitJson()) {
+    process.stdout.write(`${JSON.stringify(toolMetadataJsonForDescribe(tool, toolId))}
+`);
+    return 0;
+  }
+  printCompactToolContract(tool, toolId);
   return 0;
 }
+function toolContractJsonForDescribe(tool, requestedToolId) {
+  const toolId = String(tool.toolId || requestedToolId);
+  const inputFields = toolInputFieldsForDisplay(recordField(tool, "inputSchema", "input_schema"));
+  const usageGuidance = recordField(tool, "usageGuidance", "usage_guidance");
+  const toolExecutionResult = recordField(usageGuidance, "toolExecutionResult", "tool_execution_result");
+  const extractedLists = extractionContractEntries(
+    arrayField(toolExecutionResult, "extractedLists", "extracted_lists")
+  );
+  const extractedValues = extractionContractEntries(
+    arrayField(toolExecutionResult, "extractedValues", "extracted_values")
+  );
+  const cost = recordField(tool, "cost");
+  const deeplineCredits = numberField(tool, "deeplineCreditsPerPricingUnit", "deepline_credits_per_pricing_unit");
+  const deeplineUsdPerPricingUnit = numberField(tool, "deeplineUsdPerPricingUnit", "deepline_usd_per_pricing_unit");
+  return {
+    schemaVersion: 1,
+    toolId,
+    provider: tool.provider,
+    displayName: tool.displayName,
+    description: tool.description,
+    categories: tool.categories,
+    inputFields: inputFields.map((field) => ({
+      name: field.name,
+      type: field.type ?? "unknown",
+      required: Boolean(field.required),
+      ...field.description ? { description: field.description } : {},
+      ...Object.prototype.hasOwnProperty.call(field, "default") ? { default: field.default } : {}
+    })),
+    cost: {
+      pricingModel: stringField(cost, "pricingModel", "pricing_model") || null,
+      billingMode: stringField(cost, "billingMode", "billing_mode") || null,
+      deeplineCreditsPerPricingUnit: deeplineCredits,
+      deeplineUsdPerPricingUnit
+    },
+    getters: {
+      extractedLists,
+      extractedValues
+    },
+    executeCommand: `deepline tools execute ${toolId} --input '{...}' --json`
+  };
+}
+function extractionContractEntries(entries) {
+  return entries.flatMap((entry) => {
+    if (!isRecord4(entry)) return [];
+    const name = stringField(entry, "name");
+    const expression = stringField(entry, "expression");
+    return name && expression ? [{ name, expression }] : [];
+  });
+}
+function printCompactToolContract(tool, requestedToolId) {
+  const contract = toolContractJsonForDescribe(tool, requestedToolId);
+  const cost = isRecord4(contract.cost) ? contract.cost : {};
+  const getters = isRecord4(contract.getters) ? contract.getters : {};
+  const listGetters = Array.isArray(getters.extractedLists) ? getters.extractedLists : [];
+  const valueGetters = Array.isArray(getters.extractedValues) ? getters.extractedValues : [];
+  const inputFields = Array.isArray(contract.inputFields) ? contract.inputFields : [];
+  console.log(String(contract.toolId));
+  if (contract.displayName) console.log(`Best for: ${contract.displayName}`);
+  if (typeof contract.description === "string" && contract.description.trim()) {
+    console.log(`Description: ${contract.description.trim()}`);
+  }
+  if (Array.isArray(contract.categories) && contract.categories.length) {
+    console.log(`Tags: ${contract.categories.join(", ")}`);
+  }
+  printToolPricingOnly(tool, requestedToolId, { heading: "Cost" });
+  if (inputFields.length) {
+    console.log("");
+    console.log("Inputs:");
+    for (const field of inputFields) {
+      if (!isRecord4(field)) continue;
+      const name = stringField(field, "name");
+      if (!name) continue;
+      const required = field.required ? "*" : "";
+      const type = stringField(field, "type") || "unknown";
+      const description = stringField(field, "description");
+      console.log(`- ${name}${required}: ${type}${description ? ` - ${description}` : ""}`);
+    }
+  }
+  console.log("");
+  printToolExamplesOnly(tool, requestedToolId, { includeSamples: false });
+  if (listGetters.length || valueGetters.length) {
+    console.log("");
+    console.log("Getters:");
+    if (listGetters.length) console.log("Lists:");
+    for (const entry of listGetters) {
+      if (isRecord4(entry)) console.log(`- ${stringField(entry, "name")}: ${playResultExpression(entry)}`);
+    }
+    if (valueGetters.length) console.log("Values:");
+    for (const entry of valueGetters) {
+      if (isRecord4(entry)) console.log(`- ${stringField(entry, "name")}: ${playResultExpression(entry)}`);
+    }
+  }
+  console.log("");
+  console.log(`More: deepline tools describe ${contract.toolId} --pricing-only | --schema-only | --examples-only | --getters-only | --json`);
+}
+function printToolPricingOnly(tool, requestedToolId, options = {}) {
+  const contract = toolContractJsonForDescribe(tool, requestedToolId);
+  const cost = isRecord4(contract.cost) ? contract.cost : {};
+  const pricingModel = stringField(cost, "pricingModel") || "unknown";
+  const billingMode = stringField(cost, "billingMode") || "unknown";
+  const unit = pricingModel === "per_page" ? "page" : pricingModel === "per_result" ? "result" : pricingModel === "fixed" ? "call" : pricingModel.replace(/^per_/, "") || "unit";
+  const credits = numberField(cost, "deeplineCreditsPerPricingUnit");
+  const usd = numberField(cost, "deeplineUsdPerPricingUnit");
+  const price = credits !== null ? `${formatDecimal(credits)} Deepline credits${usd !== null ? ` / ${formatUsd(usd)}` : ""} per ${unit}` : "pricing unavailable";
+  console.log(`${options.heading ?? `Pricing: ${contract.toolId}`}: ${price}`);
+  console.log(`Billing: ${billingMode}`);
+}
+function printToolSchemaOnly(tool, requestedToolId) {
+  const contract = toolContractJsonForDescribe(tool, requestedToolId);
+  const inputFields = Array.isArray(contract.inputFields) ? contract.inputFields : [];
+  console.log(`Schema: ${contract.toolId}`);
+  if (!inputFields.length) {
+    console.log("Inputs: none");
+    return;
+  }
+  console.log("Inputs:");
+  for (const field of inputFields) {
+    if (!isRecord4(field)) continue;
+    const name = stringField(field, "name");
+    if (!name) continue;
+    const required = field.required ? "*" : "";
+    const type = stringField(field, "type") || "unknown";
+    const description = stringField(field, "description");
+    const defaultSuffix = Object.prototype.hasOwnProperty.call(field, "default") ? ` default=${JSON.stringify(field.default)}` : "";
+    console.log(`- ${name}${required}: ${type}${defaultSuffix}${description ? ` - ${description}` : ""}`);
+  }
+}
+function printToolExamplesOnly(tool, requestedToolId, options = {}) {
+  const contract = toolContractJsonForDescribe(tool, requestedToolId);
+  const toolId = String(contract.toolId);
+  const inputFields = Array.isArray(contract.inputFields) ? contract.inputFields : [];
+  const sampleInput = Object.fromEntries(
+    inputFields.slice(0, 4).flatMap((field) => {
+      if (!isRecord4(field)) return [];
+      const name = stringField(field, "name");
+      if (!name) return [];
+      return [[name, sampleValueForField(field)]];
+    })
+  );
+  console.log(`Use in a play:`);
+  console.log("```ts");
+  console.log("const result = await ctx.tools.execute({");
+  console.log(`  id: '${stableStepIdForTool(toolId)}',`);
+  console.log(`  tool: '${toolId}',`);
+  console.log(`  input: ${JSON.stringify(sampleInput || {}, null, 2).replace(/\n/g, "\n  ")},`);
+  console.log("});");
+  const getters = isRecord4(contract.getters) ? contract.getters : {};
+  const valueGetters = Array.isArray(getters.extractedValues) ? getters.extractedValues : [];
+  const listGetters = Array.isArray(getters.extractedLists) ? getters.extractedLists : [];
+  const firstGetter = [...valueGetters, ...listGetters].find(isRecord4);
+  if (firstGetter) {
+    const name = stringField(firstGetter, "name") || "value";
+    const expression = stringField(firstGetter, "expression");
+    if (expression) console.log(`const ${safeIdentifier(name)} = ${expression.replace(/^toolExecutionResult\./, "result.")};`);
+  }
+  console.log("```");
+  if (options.includeSamples !== false) {
+    const samples = recordField(tool, "samples");
+    printSamples(samples);
+  }
+}
+function printToolGettersOnly(tool, requestedToolId) {
+  const contract = toolContractJsonForDescribe(tool, requestedToolId);
+  const getters = isRecord4(contract.getters) ? contract.getters : {};
+  const listGetters = Array.isArray(getters.extractedLists) ? getters.extractedLists : [];
+  const valueGetters = Array.isArray(getters.extractedValues) ? getters.extractedValues : [];
+  console.log(`Getters: ${contract.toolId}`);
+  if (!listGetters.length && !valueGetters.length) {
+    console.log("No generated getters declared. Use --json only if you need raw metadata.");
+    return;
+  }
+  if (listGetters.length) {
+    console.log("Lists:");
+    for (const entry of listGetters) {
+      if (isRecord4(entry)) console.log(`- ${stringField(entry, "name")}: ${playResultExpression(entry)}`);
+    }
+  }
+  if (valueGetters.length) {
+    console.log("Values:");
+    for (const entry of valueGetters) {
+      if (isRecord4(entry)) console.log(`- ${stringField(entry, "name")}: ${playResultExpression(entry)}`);
+    }
+  }
+}
+function sampleValueForField(field) {
+  const name = stringField(field, "name").toLowerCase();
+  const type = stringField(field, "type").toLowerCase();
+  if (Object.prototype.hasOwnProperty.call(field, "default")) return field.default;
+  if (name.includes("email")) return "ada@example.com";
+  if (name.includes("domain") || name.includes("website")) return "example.com";
+  if (name.includes("first")) return "Ada";
+  if (name.includes("last")) return "Lovelace";
+  if (name.includes("name")) return "Ada Lovelace";
+  if (type === "integer" || type === "number") return 1;
+  if (type === "boolean") return true;
+  if (type === "array") return [];
+  if (type === "object") return {};
+  return "...";
+}
+function stableStepIdForTool(toolId) {
+  return toolId.replace(/^[a-z0-9]+_/, "").replace(/[^a-z0-9_]+/gi, "_") || "tool_call";
+}
+function safeIdentifier(name) {
+  const cleaned = name.replace(/[^a-zA-Z0-9_$]+/g, "_").replace(/^[^a-zA-Z_$]+/, "");
+  return cleaned || "value";
+}
+function playResultExpression(entry) {
+  return stringField(entry, "expression").replace(/^toolExecutionResult\./, "result.");
+}
 function toolMetadataJsonForDescribe(tool, requestedToolId) {
   const toolId = String(tool.toolId || requestedToolId);
   const {
@@ -9519,152 +10246,6 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
     }
   };
 }
-function printToolDetails(tool, requestedToolId) {
-  const toolId = String(tool.toolId || requestedToolId);
-  const operation = typeof tool.operation === "string" ? tool.operation : "";
-  const displayBase = operation && operation.startsWith(`${tool.provider}_`) ? operation.slice(String(tool.provider).length + 1) : operation ? `${tool.provider} ${operation}`.trim() : toolId;
-  const displayName = titleCase(displayBase || String(tool.displayName || toolId));
-  const cost = isRecord4(tool.cost) ? tool.cost : null;
-  const pricing = recordField(tool, "pricing");
-  const deeplineCredits = numberField(tool, "deeplineCreditsPerPricingUnit", "deepline_credits_per_pricing_unit");
-  const deeplineUsdPerPricingUnit = numberField(tool, "deeplineUsdPerPricingUnit", "deepline_usd_per_pricing_unit");
-  const billingSource = stringField(tool, "billingSource", "billing_source");
-  const billingSourceLabel = stringField(tool, "billingSourceLabel", "billing_source_label");
-  const estimatedCreditsRange = stringField(tool, "estimatedCreditsRange", "estimated_credits_range");
-  const estimatedUsdRange = stringField(tool, "estimatedUsdRange", "estimated_usd_range");
-  const estimateModelVersion = stringField(tool, "estimateModelVersion", "estimate_model_version");
-  const estimateBasedOnTools = arrayField(tool, "estimateBasedOnTools", "estimate_based_on_tools").map((item) => String(item).trim()).filter(Boolean);
-  const stepContributions = arrayField(tool, "stepContributions", "step_contributions");
-  const playExpansion = recordField(tool, "playExpansion", "play_expansion");
-  const samples = recordField(tool, "samples");
-  const usageGuidance = recordField(tool, "usageGuidance", "usage_guidance");
-  console.log(`Tool: ${toolId}`);
-  console.log("  Runtime output help:");
-  console.log("    describe shows declared schema/getters, not an observed provider response");
-  console.log(`    observe actual shape: deepline tools execute ${toolId} --input '{...}' --json`);
-  console.log("    for play getter bugs: run the play, then use the db query commands printed by runs get");
-  if (displayName) {
-    console.log("  Display name:");
-    console.log(`    ${displayName}`);
-  }
-  if (tool.categories.length > 0) {
-    console.log("  Categories:");
-    console.log(`    ${tool.categories.join(", ")}`);
-  }
-  const printedCost = printToolCost({
-    pricing,
-    cost,
-    billingSource,
-    deeplineCredits,
-    deeplineUsdPerPricingUnit
-  });
-  if (!printedCost && ["run_javascript", "call_local_codex", "call_local_claude_code"].includes(toolId)) {
-    console.log("  Cost: free");
-  }
-  if (billingSourceLabel) {
-    console.log(`  Billing source: ${billingSourceLabel}`);
-  }
-  if (estimatedCreditsRange) {
-    const usdSuffix = estimatedUsdRange ? ` (~${estimatedUsdRange})` : "";
-    console.log(`  Estimated play spend: ${estimatedCreditsRange}${usdSuffix}`);
-    if (estimateModelVersion) console.log(`    model: ${estimateModelVersion}`);
-    if (estimateBasedOnTools.length) console.log(`    based on: ${estimateBasedOnTools.join(", ")}`);
-    if (stepContributions.length) {
-      console.log("    step contributions:");
-      for (const item of stepContributions) {
-        if (!isRecord4(item)) continue;
-        const stepTool = typeof item.tool === "string" ? item.tool.trim() : "";
-        const low = typeof item.lowCredits === "number" ? item.lowCredits : null;
-        const high = typeof item.highCredits === "number" ? item.highCredits : null;
-        const lowUsd = typeof item.lowUsd === "number" ? item.lowUsd : null;
-        const highUsd = typeof item.highUsd === "number" ? item.highUsd : null;
-        if (!stepTool || low === null || high === null) continue;
-        const stepUsdSuffix = lowUsd !== null && highUsd !== null ? ` (~${formatUsd(lowUsd)}-${formatUsd(highUsd)})` : "";
-        console.log(`      - ${stepTool}: ${formatDecimal(low)}-${formatDecimal(high)} credits${stepUsdSuffix}`);
-      }
-    }
-  }
-  if (playExpansion && Object.keys(playExpansion).length > 0) {
-    const group = typeof playExpansion.group === "string" ? playExpansion.group.trim() : "";
-    console.log("  Play expansion:");
-    if (group) console.log(`    group: ${group}`);
-  }
-  const fields = toolInputFieldsForDisplay(recordField(tool, "inputSchema", "input_schema"));
-  if (fields.length) {
-    console.log("  Inputs (operation-specific):");
-    for (const field of fields) {
-      const name = String(field.name || "");
-      const typeName = String(field.type || "unknown");
-      const requiredLabel = field.required ? "required" : "optional";
-      const defaultSuffix = Object.prototype.hasOwnProperty.call(field, "default") ? `, default: ${JSON.stringify(field.default)}` : "";
-      const desc = typeof field.description === "string" && field.description.trim() ? ` - ${field.description.trim()}` : "";
-      console.log(`    - ${name} (${typeName}, ${requiredLabel}${defaultSuffix})${desc}`);
-    }
-    console.log("  Tip: pass --payload with a JSON object.");
-  }
-  printSamples(samples);
-  printUsageGuidance(usageGuidance);
-  if (isPlayTool(tool)) {
-    console.log("  Play contract:");
-    console.log("    - This is a deepline-native waterfall; the returned rows are extracted by target getters, not by hand-authored payload shape.");
-    if (playExpansion && typeof playExpansion.group === "string" && playExpansion.group.trim()) {
-      console.log(`    - Output alias/runtime group is: ${playExpansion.group.trim()}`);
-    }
-    const toolExecutionResult = recordField(usageGuidance, "toolExecutionResult");
-    const extractedValues = arrayField(toolExecutionResult, "extractedValues", "extracted_values");
-    const targets = extractedValues.map((entry) => isRecord4(entry) && typeof entry.name === "string" ? entry.name : "").filter(Boolean).sort();
-    if (targets.length) {
-      console.log(`    - Built-in extract targets: ${targets.join(", ")}`);
-    }
-  }
-  console.log("");
-  console.log("Usage:");
-  const requestPayload = samplePayload(samples, "request");
-  if (isPlayTool(tool)) {
-    if (requestPayload !== void 0) {
-      console.log(`  deepline enrich --with '${JSON.stringify({ alias: "result", tool: toolId, payload: requestPayload })}'`);
-    } else {
-      console.log(`  deepline enrich --with '{"alias":"result","tool":"${toolId}","payload":{...}}'`);
-    }
-  } else if (requestPayload !== void 0) {
-    console.log(`  deepline tools execute ${toolId} --payload '${JSON.stringify(requestPayload)}'`);
-  } else {
-    console.log(`  deepline tools execute ${toolId} --payload '{...}'`);
-  }
-  console.log("  deepline tools describe <tool_id> --json");
-}
-function printUsageGuidance(usageGuidance) {
-  if (Object.keys(usageGuidance).length === 0) return;
-  const execute = stringField(usageGuidance, "execute");
-  const toolExecutionResult = recordField(usageGuidance, "toolExecutionResult", "tool_execution_result");
-  const toolResponse = recordField(toolExecutionResult, "toolResponse", "tool_response");
-  const extractedLists = arrayField(toolExecutionResult, "extractedLists", "extracted_lists");
-  const extractedValues = arrayField(toolExecutionResult, "extractedValues", "extracted_values");
-  console.log("  Usage guidance:");
-  if (execute) console.log(`    ${execute}`);
-  const raw = stringField(toolResponse, "raw");
-  const meta = stringField(toolResponse, "meta");
-  if (raw) console.log(`    Raw tool response: ${raw}`);
-  if (meta) console.log(`    Tool response metadata: ${meta}`);
-  printExtractions("Extracted lists", extractedLists);
-  printExtractions("Extracted values", extractedValues);
-}
-function printExtractions(label, entries) {
-  if (!entries.length) return;
-  console.log(`    ${label}:`);
-  for (const entry of entries) {
-    if (!isRecord4(entry)) continue;
-    const name = stringField(entry, "name");
-    const expression = stringField(entry, "expression");
-    const details = recordField(entry, "details");
-    const rawToolOutputPaths = arrayField(details, "rawToolOutputPaths", "raw_tool_output_paths").map((value) => typeof value === "string" ? value.trim() : "").filter(Boolean);
-    const candidatePaths = arrayField(details, "candidatePaths", "candidate_paths").map((value) => typeof value === "string" ? value.trim() : "").filter(Boolean);
-    if (!name || !expression) continue;
-    const paths = candidatePaths.length ? candidatePaths : rawToolOutputPaths;
-    const pathSuffix = paths.length ? ` from ${paths.join(", ")}` : "";
-    console.log(`      - ${name}: ${expression}${pathSuffix}`);
-  }
-}
 function singleLineText(value, maxLength = 260) {
   if (typeof value !== "string") return "";
   const text = value.replace(/\s+/g, " ").trim();
@@ -9681,42 +10262,6 @@ function formatListedToolCost(tool) {
   const displayText = stringField(pricing, "displayText", "display_text");
   return displayText ? `Cost: ${displayText}` : "";
 }
-function printToolCost(input) {
-  const { pricing, cost, billingSource, deeplineCredits, deeplineUsdPerPricingUnit } = input;
-  if (billingSource === "own_provider_credentials") {
-    console.log("  Cost: free through Deepline");
-    return true;
-  }
-  const displayText = stringField(pricing, "displayText", "display_text");
-  if (displayText) {
-    console.log(`  Cost: ${displayText}`);
-    const details = arrayField(pricing, "details").map((item) => String(item).trim()).filter(Boolean);
-    if (details.length) {
-      console.log("    notes:");
-      for (const detail of details) console.log(`      - ${detail}`);
-    }
-    return true;
-  }
-  const pricingModel = cost ? typeof cost.pricingModel === "string" ? cost.pricingModel : typeof cost.pricing_model === "string" ? cost.pricing_model : "" : "";
-  const billingMode = cost ? typeof cost.billingMode === "string" ? cost.billingMode : typeof cost.billing_mode === "string" ? cost.billing_mode : "" : "";
-  if (deeplineCredits === 0) {
-    console.log("  Cost: Free");
-    return true;
-  }
-  if (pricingModel && deeplineCredits !== null) {
-    const unit = pricingModel === "per_page" ? "page" : pricingModel === "per_result" ? "result" : "call";
-    const usdText = deeplineUsdPerPricingUnit !== null ? ` / ${formatUsd(deeplineUsdPerPricingUnit)}` : "";
-    const billingSuffix = billingMode ? ` (${billingMode})` : "";
-    console.log(`  Cost: ${formatDecimal(deeplineCredits)} Deepline credits${usdText} per ${unit}${billingSuffix}`);
-    return true;
-  }
-  const summary = stringField(pricing, "summary");
-  if (summary) {
-    console.log(`  Cost: ${summary}`);
-    return true;
-  }
-  return false;
-}
 function toolInputFieldsForDisplay(inputSchema) {
   if (Array.isArray(inputSchema.fields)) return inputSchema.fields.filter(isRecord4);
   const jsonSchema = isRecord4(inputSchema.jsonSchema) ? inputSchema.jsonSchema : inputSchema;
@@ -9767,17 +10312,6 @@ function listExtractorPathsFromUsageGuidance(tool) {
     ).filter(Boolean);
   });
 }
-function isPlayTool(tool) {
-  const provider = typeof tool.provider === "string" ? tool.provider : "";
-  return provider === "deepline_native" && Boolean(recordField(tool, "playExpansion", "play_expansion"));
-}
-function titleCase(value) {
-  return value.replace(/[_-]+/g, " ").split(" ").filter(Boolean).map((part) => {
-    const lower = part.toLowerCase();
-    const special = { linkedin: "LinkedIn", crm: "CRM", api: "API" };
-    return special[lower] ?? `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`;
-  }).join(" ");
-}
 function formatDecimal(value) {
   const text = value.toFixed(12).replace(/0+$/, "").replace(/\.$/, "");
   return text || "0";
@@ -10537,6 +11071,61 @@ function shouldDeferSkillsSyncForCommand() {
   const subcommand = args[1];
   return (command === "play" || command === "plays") && subcommand === "run" && args.includes("--json");
 }
+async function runPlayRunnerHealthCheck() {
+  const dir = await mkdtemp(join11(tmpdir4(), "deepline-health-play-"));
+  const file = join11(dir, "health-check.play.ts");
+  try {
+    await writeFile4(
+      file,
+      [
+        "import { definePlay } from 'deepline';",
+        "",
+        "export default definePlay('health-check', async (ctx) => {",
+        "  const rows = await ctx",
+        "    .map('health_rows', [{ id: 'a' }, { id: 'b' }])",
+        "    .step('echo', (row) => ({ ok: true, id: row.id }))",
+        "    .run({ key: 'id' });",
+        "  return { ok: true, rows, source: 'deepline health --play-runner' };",
+        "});",
+        ""
+      ].join("\n"),
+      "utf8"
+    );
+    let capturedOutput = "";
+    const originalWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = ((chunk, ...args) => {
+      capturedOutput += typeof chunk === "string" ? chunk : String(chunk);
+      return true;
+    });
+    let exitCode = 1;
+    try {
+      exitCode = await handlePlayRun([
+        file,
+        "--input",
+        "{}",
+        "--watch",
+        "--no-open",
+        "--json"
+      ]);
+    } finally {
+      process.stdout.write = originalWrite;
+    }
+    if (exitCode !== 0) {
+      throw new Error(
+        `play runner canary exited ${exitCode}: ${capturedOutput.slice(0, 1e3)}`
+      );
+    }
+    return {
+      status: "ok",
+      playRunner: {
+        status: "ok",
+        check: "no-provider local play run completed"
+      }
+    };
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
 async function main() {
   const mainStartedAt = Date.now();
   recordCliTrace({
@@ -10548,7 +11137,7 @@ async function main() {
   if (printStartupPhase) {
     progress?.phase("loading deepline cli");
   }
-  const program = new Command2();
+  const program = new Command3();
   program.name("deepline").description("Deepline CLI (TypeScript SDK)").version(SDK_VERSION, "-v, --version", "Show version").showHelpAfterError().showSuggestionAfterError(true).addHelpText(
     "after",
     `
@@ -10557,7 +11146,7 @@ Common commands:
   deepline auth status --json
   deepline plays search email --json
   deepline plays describe person-linkedin-to-email --json
-  deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
+  deepline plays run my.play.ts --input '{"domain":"stripe.com"}'
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
   deepline update
 
@@ -10613,18 +11202,30 @@ Exit codes:
   registerDbCommands(program);
   registerFeedbackCommands(program);
   registerUpdateCommand(program);
-  program.command("health").description("Check server health.").option("--json", "Force JSON output.").addHelpText(
+  program.command("health").description("Check server health.").option("--json", "Force JSON output.").option(
+    "--play-runner",
+    "Run a tiny no-provider play to verify the full play execution plane."
+  ).addHelpText(
     "after",
     `
 Notes:
   Read-only connectivity check for the configured Deepline host. Prints the raw
   server health payload as JSON.
+  Add --play-runner to verify bundling, coordinator dispatch, runtime callbacks,
+  and run streaming with a tiny no-provider play.
 
 Examples:
   deepline health
+  deepline health --play-runner
 `
-  ).action(async () => {
+  ).action(async (options) => {
     try {
+      if (options.playRunner) {
+        const data2 = await runPlayRunnerHealthCheck();
+        process.stdout.write(`${JSON.stringify(data2, null, 2)}
+`);
+        return;
+      }
       const client = new DeeplineClient();
       const data = await client.health();
       process.stdout.write(`${JSON.stringify(data, null, 2)}