deepline 0.1.55 → 0.1.57

package/dist/cli/index.js

@@ -220,10 +220,10 @@ function resolveConfig(options) {
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.55",
-  apiContract: "2026-05-run-response-package",
+  version: "0.1.57",
+  apiContract: "2026-05-play-tool-describe-starters",
   supportPolicy: {
-    latest: "0.1.55",
+    latest: "0.1.57",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -727,6 +727,23 @@ var DeeplineClient = class {
     }
     return `deepline plays run ${target} --input '{...}' --watch`;
   }
+  starterPlayPath(play) {
+    const target = play.reference || play.name;
+    const unqualifiedName = target.split("/").pop() || play.name;
+    const safeName = unqualifiedName.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+    return `./${safeName || "play"}.play.ts`;
+  }
+  playCloneEditStarter(play) {
+    const readonlyPrebuilt = (play.origin === "prebuilt" || play.ownerType === "deepline") && !play.canEdit;
+    if (!play.canClone && !readonlyPrebuilt) return void 0;
+    const target = play.reference || play.name;
+    const path = this.starterPlayPath(play);
+    return {
+      path,
+      command: `deepline plays get ${target} --source --out ${path}`,
+      checkCommand: `deepline plays check ${path}`
+    };
+  }
   summarizePlayListItem(play, options) {
     const aliases = play.aliases?.length ? play.aliases : [play.name];
     const csvInput = this.schemaMetadata(play.inputSchema, "csvInput");
@@ -735,6 +752,7 @@ var DeeplineClient = class {
       "rowOutputSchema"
     );
     const runCommand2 = this.playRunCommand(play, { csvInput });
+    const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
       ...play.reference ? { reference: play.reference } : {},
@@ -750,6 +768,7 @@ var DeeplineClient = class {
       ...rowOutputSchema ? { rowOutputSchema } : {},
       runCommand: runCommand2,
       examples: [runCommand2],
+      ...cloneEditStarter ? { cloneEditStarter } : {},
       currentPublishedVersion: play.currentPublishedVersion ?? null,
       isDraftDirty: play.isDraftDirty
     };
@@ -1452,7 +1471,6 @@ var DeeplineClient = class {
   async searchPlays(options) {
     const params = new URLSearchParams();
     params.set("search", options.query.trim());
-    if (options.origin) params.set("origin", options.origin);
     const response = await this.http.get(
       `/api/v2/plays?${params.toString()}`
     );
@@ -5717,6 +5735,204 @@ function createCliProgress(enabled) {
   return progress;
 }
 
+// ../shared_libs/plays/row-identity.ts
+var POSTGRES_IDENTIFIER_MAX_LENGTH = 63;
+var PLAY_NAME_MAX_LENGTH = POSTGRES_IDENTIFIER_MAX_LENGTH;
+var MAP_KEY_NAMESPACE_MAX_LENGTH = POSTGRES_IDENTIFIER_MAX_LENGTH;
+var SHA256_INITIAL_HASH = [
+  1779033703,
+  3144134277,
+  1013904242,
+  2773480762,
+  1359893119,
+  2600822924,
+  528734635,
+  1541459225
+];
+var SHA256_ROUND_CONSTANTS = [
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+];
+function rightRotate32(value, bits) {
+  return value >>> bits | value << 32 - bits;
+}
+function sha256Hex(input) {
+  const bytes = Array.from(new TextEncoder().encode(input));
+  const bitLength = bytes.length * 8;
+  bytes.push(128);
+  while (bytes.length % 64 !== 56) {
+    bytes.push(0);
+  }
+  const highBits = Math.floor(bitLength / 4294967296);
+  const lowBits = bitLength >>> 0;
+  bytes.push(
+    highBits >>> 24 & 255,
+    highBits >>> 16 & 255,
+    highBits >>> 8 & 255,
+    highBits & 255,
+    lowBits >>> 24 & 255,
+    lowBits >>> 16 & 255,
+    lowBits >>> 8 & 255,
+    lowBits & 255
+  );
+  const hash = [...SHA256_INITIAL_HASH];
+  const words = new Array(64).fill(0);
+  for (let offset = 0; offset < bytes.length; offset += 64) {
+    for (let index = 0; index < 16; index += 1) {
+      const wordOffset = offset + index * 4;
+      words[index] = (bytes[wordOffset] ?? 0) << 24 | (bytes[wordOffset + 1] ?? 0) << 16 | (bytes[wordOffset + 2] ?? 0) << 8 | (bytes[wordOffset + 3] ?? 0);
+    }
+    for (let index = 16; index < 64; index += 1) {
+      const s0 = rightRotate32(words[index - 15], 7) ^ rightRotate32(words[index - 15], 18) ^ words[index - 15] >>> 3;
+      const s1 = rightRotate32(words[index - 2], 17) ^ rightRotate32(words[index - 2], 19) ^ words[index - 2] >>> 10;
+      words[index] = words[index - 16] + s0 + words[index - 7] + s1 >>> 0;
+    }
+    let [a, b, c, d, e, f, g, h] = hash;
+    for (let index = 0; index < 64; index += 1) {
+      const s1 = rightRotate32(e, 6) ^ rightRotate32(e, 11) ^ rightRotate32(e, 25);
+      const ch = e & f ^ ~e & g;
+      const temp1 = h + s1 + ch + SHA256_ROUND_CONSTANTS[index] + words[index] >>> 0;
+      const s0 = rightRotate32(a, 2) ^ rightRotate32(a, 13) ^ rightRotate32(a, 22);
+      const maj = a & b ^ a & c ^ b & c;
+      const temp2 = s0 + maj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    hash[0] = hash[0] + a >>> 0;
+    hash[1] = hash[1] + b >>> 0;
+    hash[2] = hash[2] + c >>> 0;
+    hash[3] = hash[3] + d >>> 0;
+    hash[4] = hash[4] + e >>> 0;
+    hash[5] = hash[5] + f >>> 0;
+    hash[6] = hash[6] + g >>> 0;
+    hash[7] = hash[7] + h >>> 0;
+  }
+  return hash.map((word) => word.toString(16).padStart(8, "0")).join("");
+}
+function sanitizeIdentifierPart(value) {
+  return value.trim().replace(/[^a-z0-9]+/gi, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+}
+function validateIdentifierPart(rawValue, label, maxLength) {
+  const sanitized = sanitizeIdentifierPart(rawValue);
+  if (!sanitized) {
+    throw new Error(
+      `${label} must contain at least one letter or number after normalization. Use only letters, numbers, underscores, or hyphens.`
+    );
+  }
+  if (sanitized.length > maxLength) {
+    throw new Error(
+      `${label} is too long after normalization (${sanitized.length}/${maxLength}). Shorten it to ${maxLength} characters or fewer. Normalized value: "${sanitized}".`
+    );
+  }
+  return sanitized;
+}
+function normalizePlayName(value) {
+  if (value.includes("/")) {
+    throw new Error(
+      'Play name cannot contain "/". Slash is reserved for qualified play references like "prebuilt/example" or "self/example".'
+    );
+  }
+  return validateIdentifierPart(value, "Play name", PLAY_NAME_MAX_LENGTH);
+}
+function normalizePlayNameForSheet(value) {
+  if (!value.includes("/")) {
+    return normalizePlayName(value);
+  }
+  const digest = sha256Hex(value).slice(0, 12);
+  const normalizedReference = sanitizeIdentifierPart(
+    value.replace(/\//g, "__")
+  );
+  const prefixLength = Math.max(1, PLAY_NAME_MAX_LENGTH - digest.length - 1);
+  const prefix = normalizedReference.slice(0, prefixLength).replace(/_+$/g, "") || "qualified_play";
+  return `${prefix}_${digest}`;
+}
+function normalizeTableNamespace(value) {
+  return validateIdentifierPart(
+    value,
+    "ctx.map() key",
+    MAP_KEY_NAMESPACE_MAX_LENGTH
+  );
+}
+function validatePlaySheetTableName(playName, tableNamespace) {
+  const playSegment = normalizePlayNameForSheet(playName);
+  const keySegment = normalizeTableNamespace(tableNamespace);
+  const resolved = `${playSegment}_${keySegment}`;
+  if (resolved.length > POSTGRES_IDENTIFIER_MAX_LENGTH) {
+    throw new Error(
+      `Play sheet table name is too long after normalization (${resolved.length}/63). Shorten the play name or ctx.map() key. Resolved table name: "${resolved}".`
+    );
+  }
+  return resolved;
+}
+
 // src/cli/trace.ts
 var cliTraceStartedAt = Date.now();
 function isTruthyEnv(value) {
@@ -5765,6 +5981,31 @@ async function traceCliSpan(phase, fields, run) {
   }
 }
 
+// src/cli/play-check-hints.ts
+var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific fields.";
+function sourceLineForError(sourceCode, error) {
+  const match = error.match(/:(\d+):(\d+)\s/);
+  const lineNumber = match?.[1] ? Number(match[1]) : NaN;
+  if (!Number.isInteger(lineNumber) || lineNumber < 1) return "";
+  return sourceCode.split(/\r?\n/)[lineNumber - 1] ?? "";
+}
+function looksLikeInvalidExtractedGetter(error, sourceLine) {
+  if (!/Property '[^']+' does not exist on type/.test(error)) return false;
+  return /\bextracted(?:Values|Lists)\s*\./.test(sourceLine);
+}
+function addPlayCheckRepairHints(input) {
+  let addedHint = false;
+  return input.errors.map((error) => {
+    const line = sourceLineForError(input.sourceCode, error);
+    if (addedHint || !looksLikeInvalidExtractedGetter(error, line) || error.includes(EXTRACTED_GETTER_ERROR_HINT)) {
+      return error;
+    }
+    addedHint = true;
+    return `${error}
+${EXTRACTED_GETTER_ERROR_HINT}`;
+  });
+}
+
 // src/cli/commands/play.ts
 var PLAY_RUN_RESERVED_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--json",
@@ -5844,9 +6085,23 @@ function formatPlayListReference(play) {
   return play.reference || play.name;
 }
 function defaultMaterializedPlayPath(reference) {
+  return (0, import_node_path10.resolve)(defaultStarterPlayPath(reference));
+}
+function defaultStarterPlayPath(reference) {
   const playName = parseReferencedPlayTarget(reference).unqualifiedPlayName;
   const safeName = playName.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-  return (0, import_node_path10.resolve)(`${safeName || "play"}.play.ts`);
+  return `./${safeName || "play"}.play.ts`;
+}
+function buildCloneEditStarter(play) {
+  const readonlyPrebuilt = (play.origin === "prebuilt" || play.ownerType === "deepline") && !play.canEdit;
+  if (!play.canClone && !readonlyPrebuilt) return void 0;
+  const reference = play.reference || play.name;
+  const path = defaultStarterPlayPath(reference);
+  return {
+    path,
+    command: `deepline plays get ${reference} --source --out ${path}`,
+    checkCommand: `deepline plays check ${path}`
+  };
 }
 function materializeRemotePlaySource(input) {
   if (isFileTarget(input.target)) {
@@ -6292,6 +6547,8 @@ var TERMINAL_PLAY_STATUSES2 = /* @__PURE__ */ new Set([
   "cancelled"
 ]);
 var PLAY_START_TRANSIENT_RETRY_DELAYS_MS = [500, 1500];
+var PLAY_CUSTOMER_STORAGE_SCHEMA_NAME = "storage";
+var PLAY_INTERNAL_STEP_RECEIPT_TABLE = "_deepline_step_receipts";
 function getEventPayload(event) {
   return event.payload && typeof event.payload === "object" ? event.payload : {};
 }
@@ -6345,6 +6602,86 @@ function getLogLinesFromLiveEvent(event) {
   const lines = getEventPayload(event).lines;
   return Array.isArray(lines) ? lines.filter((line) => typeof line === "string") : [];
 }
+function quoteSqlIdentifier(identifier) {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+function quoteSqlLiteral(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+function buildDebugDbQueryCommand(sql) {
+  return `deepline db query --sql ${shellSingleQuote(sql)} --max-rows 20 --json`;
+}
+function buildStepReceiptsDebugCommand(runId) {
+  const table = `${quoteSqlIdentifier(
+    PLAY_CUSTOMER_STORAGE_SCHEMA_NAME
+  )}.${quoteSqlIdentifier(PLAY_INTERNAL_STEP_RECEIPT_TABLE)}`;
+  const sql = `select convert_from(k, 'UTF8') as receipt_key, case status when 0 then 'pending' when 1 then 'running' when 2 then 'completed' when 3 then 'failed' when 4 then 'skipped' else status::text end as status, output, error, updated_at from ${table} where run_id = ${quoteSqlLiteral(runId)} order by updated_at asc, receipt_key asc limit 20`;
+  return buildDebugDbQueryCommand(sql);
+}
+function buildMapTableDebugCommand(input) {
+  try {
+    const tableName = validatePlaySheetTableName(
+      input.playName,
+      input.tableNamespace
+    );
+    const table = `${quoteSqlIdentifier(
+      PLAY_CUSTOMER_STORAGE_SCHEMA_NAME
+    )}.${quoteSqlIdentifier(tableName)}`;
+    const sql = `select * from ${table} where _run_id = ${quoteSqlLiteral(input.runId)} limit 20`;
+    return buildDebugDbQueryCommand(sql);
+  } catch {
+    return null;
+  }
+}
+function extractTableNamespaceFromLiveEvent(event) {
+  const payload = getEventPayload(event);
+  const candidates = [
+    payload.artifactTableNamespace,
+    payload.tableNamespace,
+    payload.mapNodeId
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return null;
+}
+function emitLiveDebugTableHints(input) {
+  if (input.jsonOutput || !input.runId || input.runId === "pending") {
+    return;
+  }
+  input.state.emittedDebugKeys ??= /* @__PURE__ */ new Set();
+  const receiptsKey = `receipts:${input.runId}`;
+  if (!input.state.emittedDebugKeys.has(receiptsKey)) {
+    input.state.emittedDebugKeys.add(receiptsKey);
+    input.progress.writeLine(
+      `Debug top-level outputs: ${buildStepReceiptsDebugCommand(input.runId)}`,
+      process.stdout
+    );
+  }
+  const tableNamespace = extractTableNamespaceFromLiveEvent(input.event);
+  if (!tableNamespace) {
+    return;
+  }
+  const tableKey = `table:${input.runId}:${tableNamespace}`;
+  if (input.state.emittedDebugKeys.has(tableKey)) {
+    return;
+  }
+  const command = buildMapTableDebugCommand({
+    playName: input.playName,
+    runId: input.runId,
+    tableNamespace
+  });
+  if (!command) {
+    return;
+  }
+  input.state.emittedDebugKeys.add(tableKey);
+  input.progress.writeLine(
+    `Debug rows for ${tableNamespace}: ${command}`,
+    process.stdout
+  );
+}
 function describeLiveEventPhase(event) {
   const payload = getEventPayload(event);
   if (event.type === "play.run.status") {
@@ -6497,6 +6834,14 @@ async function waitForPlayCompletionByStream(input) {
         lastPhase = phase;
         input.progress.phase(phase);
       }
+      emitLiveDebugTableHints({
+        event,
+        playName: input.playName,
+        runId: input.workflowId,
+        jsonOutput: input.jsonOutput,
+        state: input.state,
+        progress: input.progress
+      });
       printPlayLogLines({
         lines: getLogLinesFromLiveEvent(event),
         status: null,
@@ -6645,6 +6990,14 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
         state,
         progress: input.progress
       });
+      emitLiveDebugTableHints({
+        event,
+        playName: input.playName,
+        runId: workflowId,
+        jsonOutput: input.jsonOutput,
+        state,
+        progress: input.progress
+      });
       if (!input.jsonOutput) {
         printPlayProgressLines({
           lines: getProgressLinesFromLiveEvent(event),
@@ -6700,6 +7053,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
       });
       return waitForPlayCompletionByStream({
         client: input.client,
+        playName: input.playName,
         workflowId: lastKnownWorkflowId,
         dashboardUrl,
         jsonOutput: input.jsonOutput,
@@ -6735,6 +7089,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
     });
     return waitForPlayCompletionByStream({
       client: input.client,
+      playName: input.playName,
       workflowId: lastKnownWorkflowId,
       dashboardUrl,
       jsonOutput: input.jsonOutput,
@@ -8118,6 +8473,10 @@ async function handlePlayCheck(args) {
   });
   const enrichedResult = {
     ...result,
+    errors: result.valid ? result.errors : addPlayCheckRepairHints({
+      errors: result.errors,
+      sourceCode: graph.root.sourceCode
+    }),
     toolGetterHints: result.toolGetterHints ?? await buildToolGetterHints(client, result.staticPipeline)
   };
   if (options.jsonOutput) {
@@ -8903,25 +9262,13 @@ function parsePlaySearchOptions(args) {
   const query = args[0]?.trim();
   if (!query) {
     throw new Error(
-      "Usage: deepline plays search <query> [--origin prebuilt|owned] [--compact] [--json]"
+      "Usage: deepline plays search <query> [--compact] [--json]"
     );
   }
-  let origin;
-  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;
-    }
-  }
   return {
     query,
     jsonOutput: argsWantJson(args),
-    compact: args.includes("--compact"),
-    origin
+    compact: args.includes("--compact")
   };
 }
 function printPlayDescription(play) {
@@ -8970,10 +9317,10 @@ function printPlayDescription(play) {
     }
   }
   console.log(`  Run: ${play.runCommand}`);
-  if (play.origin === "prebuilt" && !play.canEdit) {
-    console.log(
-      `  Customize: deepline plays get ${reference} --source --out ./my-play.play.ts`
-    );
+  const cloneEditStarter = play.cloneEditStarter ?? buildCloneEditStarter(play);
+  if (cloneEditStarter) {
+    console.log(`  Clone/edit starter: ${cloneEditStarter.command}`);
+    console.log(`  Check starter: ${cloneEditStarter.checkCommand}`);
   }
 }
 function compactPlaySchema(schema) {
@@ -9005,6 +9352,7 @@ function summarizePlayListItemForCli(play, options) {
   const csvInput = playSchemaMetadata(play.inputSchema, "csvInput");
   const rowOutputSchema = playSchemaMetadata(play.outputSchema, "rowOutputSchema");
   const runCommand2 = playRunCommand(play, { csvInput });
+  const cloneEditStarter = buildCloneEditStarter(play);
   return {
     name: play.name,
     ...play.reference ? { reference: play.reference } : {},
@@ -9020,6 +9368,7 @@ function summarizePlayListItemForCli(play, options) {
     ...rowOutputSchema ? { rowOutputSchema } : {},
     runCommand: runCommand2,
     examples: [runCommand2],
+    ...cloneEditStarter ? { cloneEditStarter } : {},
     currentPublishedVersion: play.currentPublishedVersion ?? null,
     isDraftDirty: play.isDraftDirty
   };
@@ -9035,7 +9384,6 @@ async function handlePlaySearch(args) {
   const client = new DeeplineClient();
   const plays = await client.searchPlays({
     query: options.query,
-    ...options.origin ? { origin: options.origin } : {},
     compact: options.compact
   });
   if (options.jsonOutput) {
@@ -9081,20 +9429,12 @@ function matchesPlayGrepQuery(value, query, mode) {
 async function handlePlayGrep(args) {
   const query = args[0]?.trim();
   if (!query) {
-    console.error("Usage: deepline plays grep <query> [--origin prebuilt|owned] [--compact] [--json]");
+    console.error("Usage: deepline plays grep <query> [--mode all|any|phrase] [--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";
@@ -9104,13 +9444,8 @@ async function handlePlayGrep(args) {
   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(
+    grepMode: mode
+  })).filter(
     (play) => matchesPlayGrepQuery(
       {
         name: play.name,
@@ -9131,8 +9466,7 @@ async function handlePlayGrep(args) {
       plays,
       count: plays.length,
       query,
-      grep: { mode, terms: parsePlayGrepTerms(query, mode) },
-      filters: { origin: origin ?? null }
+      grep: { mode, terms: parsePlayGrepTerms(query, mode) }
     })}
 `);
     return 0;
@@ -9468,7 +9802,7 @@ Notes:
 Examples:
   deepline plays list
   deepline plays list --origin prebuilt --json
-  deepline plays search email --origin prebuilt --json
+  deepline plays search email --json
 `
   ).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([
@@ -9480,20 +9814,18 @@ Examples:
     "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.
+  Ranked discovery for workflows. 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 grep "linkedin to email" --origin prebuilt --compact --json
+  deepline plays grep "linkedin to email" --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) => {
+  ).option("--compact", "Emit compact schemas").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await handlePlaySearch([
       query,
-      ...options.origin ? ["--origin", options.origin] : [],
       ...options.compact ? ["--compact"] : [],
       ...options.json ? ["--json"] : []
     ]);
@@ -9509,14 +9841,13 @@ Notes:
   --mode all for AND.
 
 Examples:
-  deepline plays grep email --origin prebuilt --json
-  deepline plays grep "company contact" --origin prebuilt --mode all --json
+  deepline plays grep email --json
+  deepline plays grep "company contact" --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) => {
+  ).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"] : []
@@ -9532,6 +9863,7 @@ Notes:
 Examples:
   deepline plays describe person-linkedin-to-email
   deepline plays describe person-linkedin-to-email --json
+  deepline plays get prebuilt/person-linkedin-to-email --source --out ./person-linkedin-to-email.play.ts
 `
   ).option("--compact", "Emit compact schemas").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
     process.exitCode = await handlePlayDescribe([
@@ -10356,6 +10688,11 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
   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");
+  const starterScript = seedToolListScript({
+    toolId,
+    payload: samplePayloadForInputFields(inputFields),
+    rows: []
+  });
   return {
     schemaVersion: 1,
     toolId,
@@ -10380,7 +10717,16 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
       extractedLists,
       extractedValues
     },
-    executeCommand: `deepline tools execute ${toolId} --input '{...}' --json`
+    executeCommand: `deepline tools execute ${toolId} --input '{...}' --json`,
+    starterScript: {
+      path: starterScript.path,
+      sourceCode: starterScript.sourceCode,
+      projectDir: starterScript.projectDir,
+      copyToProject: {
+        macosLinux: starterScript.macCopyCommand,
+        windowsPowerShell: starterScript.windowsCopyCommand
+      }
+    }
   };
 }
 function extractionContractEntries(entries) {
@@ -10422,6 +10768,13 @@ function printCompactToolContract(tool, requestedToolId) {
   }
   console.log("");
   printToolExamplesOnly(tool, requestedToolId, { includeSamples: false });
+  const starterScript = isRecord4(contract.starterScript) ? contract.starterScript : {};
+  const starterPath = stringField(starterScript, "path");
+  if (starterPath) {
+    console.log("");
+    console.log(`Starter script: ${starterPath}`);
+    console.log("Copy it into your project and replace the sample input with the proven probe payload.");
+  }
   if (listGetters.length || valueGetters.length) {
     console.log("");
     console.log("Getters:");
@@ -10473,14 +10826,7 @@ 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)]];
-    })
-  );
+  const sampleInput = samplePayloadForInputFields(inputFields);
   console.log(`Use in a play:`);
   console.log("```ts");
   console.log("const result = await ctx.tools.execute({");
@@ -10541,6 +10887,16 @@ function sampleValueForField(field) {
   if (type === "object") return {};
   return "...";
 }
+function samplePayloadForInputFields(fields) {
+  return Object.fromEntries(
+    fields.slice(0, 4).flatMap((field) => {
+      if (!isRecord4(field)) return [];
+      const name = stringField(field, "name");
+      if (!name) return [];
+      return [[name, sampleValueForField(field)]];
+    })
+  );
+}
 function stableStepIdForTool(toolId) {
   return toolId.replace(/^[a-z0-9]+_/, "").replace(/[^a-z0-9_]+/gi, "_") || "tool_call";
 }
@@ -10553,6 +10909,12 @@ function playResultExpression(entry) {
 }
 function toolMetadataJsonForDescribe(tool, requestedToolId) {
   const toolId = String(tool.toolId || requestedToolId);
+  const inputFields = toolInputFieldsForDisplay(recordField(tool, "inputSchema", "input_schema"));
+  const starterScript = seedToolListScript({
+    toolId,
+    payload: samplePayloadForInputFields(inputFields),
+    rows: []
+  });
   const {
     cost: _cost,
     deeplineCreditsPerPricingUnit: _deeplineCreditsPerPricingUnit,
@@ -10572,12 +10934,48 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
     toolId,
     provider: tool.provider,
     displayName: tool.displayName,
+    usageGuidance: usageGuidanceWithAccessDefaults(recordField(tool, "usageGuidance", "usage_guidance")),
     runtimeOutputHelp: {
-      contract: "tools describe shows the declared schema and semantic getters; it is not an observed provider response.",
+      contract: "tools describe shows declared schema and Deepline getters; it is not an observed provider response.",
+      getterScope: "extractedValues/extractedLists .get() only works for declared Deepline getters listed in usageGuidance.toolExecutionResult.",
+      rawToolResponse: "Use toolExecutionResult.toolResponse.raw for provider/tool-specific fields, fields in outputSchema that are not declared getters, and debugging.",
+      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter.",
       observeActualShape: `deepline tools execute ${toolId} --input '{...}' --json`,
       observedOutput: `deepline tools execute ${toolId} --input '{...}' --json`,
       forPlayGetterBugs: "Run the play, then inspect the emitted table commands from runs get. Use deepline db query against the run tables before editing getters.",
       executeOutputFields: "tools execute JSON may include output_preview for this direct probe only; play debugging uses run tables."
+    },
+    starterScript: {
+      path: starterScript.path,
+      sourceCode: starterScript.sourceCode,
+      projectDir: starterScript.projectDir,
+      copyToProject: {
+        macosLinux: starterScript.macCopyCommand,
+        windowsPowerShell: starterScript.windowsCopyCommand
+      }
+    }
+  };
+}
+function usageGuidanceWithAccessDefaults(usageGuidance) {
+  if (Object.keys(usageGuidance).length === 0) return usageGuidance;
+  const existingAccess = recordField(usageGuidance, "access");
+  return {
+    ...usageGuidance,
+    access: {
+      extractedLists: {
+        expression: "toolExecutionResult.extractedLists.<name>.get()",
+        meaning: "Declared Deepline list extractors only."
+      },
+      extractedValues: {
+        expression: "toolExecutionResult.extractedValues.<name>.get()",
+        meaning: "Declared Deepline scalar extractors only."
+      },
+      rawToolResponse: {
+        expression: "toolExecutionResult.toolResponse.raw",
+        meaning: "Raw tool response for provider/tool-specific fields and debugging."
+      },
+      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; use toolResponse.raw for provider/tool-specific fields.",
+      ...existingAccess
     }
   };
 }
@@ -10794,6 +11192,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   (0, import_node_fs10.writeFileSync)(scriptPath, script, { encoding: "utf-8", mode: 384 });
   return {
     path: scriptPath,
+    sourceCode: script,
     projectDir,
     macCopyCommand: `mkdir -p ${shellQuote(projectDir)} && cp ${shellQuote(scriptPath)} ${shellQuote(`${projectDir}/${fileName}`)}`,
     windowsCopyCommand: `New-Item -ItemType Directory -Force -Path ${powerShellQuote(projectDir.replace(/\//g, "\\"))} | Out-Null; Copy-Item -LiteralPath ${powerShellQuote(scriptPath)} -Destination ${powerShellQuote(`${projectDir.replace(/\//g, "\\")}\\${fileName}`)}`