deepline 0.1.46 → 0.1.48

package/README.md

@@ -50,10 +50,10 @@ cd sdk && bun run build    # or: npm run sdk:build from root
 
 ## Env files
 
-| File                                 | Set by              | Contains                                  |
-| ------------------------------------ | ------------------- | ----------------------------------------- |
-| `~/.local/deepline/<host-slug>/.env` | SDK `auth register` | `DEEPLINE_HOST_URL`, `DEEPLINE_API_KEY`   |
-| `.env.deepline`                      | Developer/agent     | `DEEPLINE_HOST_URL`, `DEEPLINE_API_KEY`   |
+| File                                 | Set by              | Contains                                |
+| ------------------------------------ | ------------------- | --------------------------------------- |
+| `~/.local/deepline/<host-slug>/.env` | SDK `auth register` | `DEEPLINE_HOST_URL`, `DEEPLINE_API_KEY` |
+| `.env.deepline`                      | Developer/agent     | `DEEPLINE_HOST_URL`, `DEEPLINE_API_KEY` |
 
 The SDK CLI env contract is only `DEEPLINE_HOST_URL` and `DEEPLINE_API_KEY`.
 Do not route the SDK CLI through `.env`, `.env.local`, or `.env.worktree`.
@@ -257,27 +257,27 @@ export default definePlay('rate-limit-waterfall', async (ctx) => {
 
   const probeFallback = steps<{ lead_id: string; row_number: number }>()
     .step("primary_probe", (row, ctx) =>
-      ctx.tool({
+      ctx.tools.execute({
         id: 'rate_limit_probe',
         tool: 'test_rate_limit',
         input: {
-        key: 'redis-shared-scenario',
-        lead_id: row.lead_id,
-        row_number: row.row_number,
-      },
+          key: 'redis-shared-scenario',
+          lead_id: row.lead_id,
+          row_number: row.row_number,
+        },
         description: 'Exercise primary rate-limit behavior.',
       }))
     .step("backup_probe", when(
       (row) => !row.primary_probe,
       (row, ctx) =>
-        ctx.tool({
+        ctx.tools.execute({
           id: 'rate_limit_probe_backup',
           tool: 'test_rate_limit',
           input: {
-          key: 'redis-shared-scenario',
-          lead_id: row.lead_id,
-          row_number: row.row_number,
-        },
+            key: 'redis-shared-scenario',
+            lead_id: row.lead_id,
+            row_number: row.row_number,
+          },
           description: 'Exercise fallback rate-limit behavior.',
         }),
     ))

package/dist/cli/index.js

@@ -216,7 +216,7 @@ function resolveConfig(options) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.46";
+var SDK_VERSION = "0.1.48";
 var SDK_API_CONTRACT = "2026-05-stripe-promo-checkout";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
@@ -2795,8 +2795,10 @@ async function handleCheckout(options) {
 }
 async function handleRedeemCode(code, options) {
   const { http } = getAuthedHttpClient();
-  const payload = await http.post("/api/v2/billing/checkout/verify", { code });
-  const url = String(payload.url || "");
+  const payload = await http.post("/api/v2/billing/checkout", {
+    discountCode: code
+  });
+  const url = String(payload.url || payload.checkout_url || "");
   if (!options.json && !options.noOpen && url) openInBrowser(url);
   printCommandEnvelope({
     ...payload,
@@ -9232,11 +9234,16 @@ function extractSummaryFields(payload) {
 }
 
 // src/cli/commands/tools.ts
+var TOOL_COMMAND_TEMPLATES = {
+  describe: "deepline tools describe <toolId>",
+  execute: "deepline tools execute <toolId> --input '{...}'"
+};
 function toListedTool(tool) {
   if (isPlayLikeTool(tool)) {
     const playReference = playReferenceForTool(tool);
     return {
       ...tool,
+      description: listedToolDescription(tool),
       id: tool.toolId,
       type: "play",
       executeCommand: `deepline plays run ${playReference} --input '{...}' --watch`
@@ -9244,6 +9251,7 @@ function toListedTool(tool) {
   }
   return {
     ...tool,
+    description: listedToolDescription(tool),
     id: tool.toolId,
     type: "tool",
     executeCommand: `deepline tools execute ${tool.toolId}`
@@ -9256,14 +9264,29 @@ async function listTools(args) {
     sections: [
       {
         title: `${items.length} tools available:`,
-        lines: items.flatMap((item) => {
+        lines: items.map((item) => {
           const cats = item.categories.length ? ` [${item.categories.join(", ")}]` : "";
-          return [`${item.toolId}${cats}`, `  ${item.description}`];
+          const pricing = formatListedToolCost(item);
+          return `${item.toolId}${cats} - ${item.description}${pricing ? ` - ${pricing}` : ""}`;
         })
+      },
+      {
+        title: "next",
+        lines: [
+          "Run `deepline tools describe <toolId>` before executing a tool."
+        ]
       }
     ]
   };
-  printCommandEnvelope({ tools: items, count: items.length, render }, { json: argsWantJson(args) });
+  printCommandEnvelope(
+    {
+      tools: items,
+      count: items.length,
+      commandTemplates: TOOL_COMMAND_TEMPLATES,
+      render
+    },
+    { json: argsWantJson(args) }
+  );
   return 0;
 }
 async function searchTools(queryInput, options = {}) {
@@ -9481,8 +9504,22 @@ async function getTool(args) {
 }
 function toolMetadataJsonForDescribe(tool, requestedToolId) {
   const toolId = String(tool.toolId || requestedToolId);
+  const {
+    cost: _cost,
+    deeplineCreditsPerPricingUnit: _deeplineCreditsPerPricingUnit,
+    deeplineUsdPerPricingUnit: _deeplineUsdPerPricingUnit,
+    deeplineUsdPerCredit: _deeplineUsdPerCredit,
+    deeplinePricingSummary: _deeplinePricingSummary,
+    deeplinePricingDetails: _deeplinePricingDetails,
+    deepline_credits_per_pricing_unit: _snakeDeeplineCreditsPerPricingUnit,
+    deepline_usd_per_pricing_unit: _snakeDeeplineUsdPerPricingUnit,
+    deepline_usd_per_credit: _snakeDeeplineUsdPerCredit,
+    deepline_pricing_summary: _snakeDeeplinePricingSummary,
+    deepline_pricing_details: _snakeDeeplinePricingDetails,
+    ...publicTool
+  } = tool;
   return {
-    ...tool,
+    ...publicTool,
     toolId,
     provider: tool.provider,
     displayName: tool.displayName,
@@ -9501,9 +9538,9 @@ function printToolDetails(tool, requestedToolId) {
   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 deeplineUsdPerCredit = numberField(tool, "deeplineUsdPerCredit", "deepline_usd_per_credit");
   const billingSource = stringField(tool, "billingSource", "billing_source");
   const billingSourceLabel = stringField(tool, "billingSourceLabel", "billing_source_label");
   const estimatedCreditsRange = stringField(tool, "estimatedCreditsRange", "estimated_credits_range");
@@ -9528,6 +9565,7 @@ function printToolDetails(tool, requestedToolId) {
     console.log(`    ${tool.categories.join(", ")}`);
   }
   const printedCost = printToolCost({
+    pricing,
     cost,
     billingSource,
     deeplineCredits,
@@ -9539,9 +9577,6 @@ function printToolDetails(tool, requestedToolId) {
   if (billingSourceLabel) {
     console.log(`  Billing source: ${billingSourceLabel}`);
   }
-  if (typeof deeplineUsdPerCredit === "number") {
-    console.log(`  Deepline rate: $${deeplineUsdPerCredit.toFixed(2)} per credit`);
-  }
   if (estimatedCreditsRange) {
     const usdSuffix = estimatedUsdRange ? ` (~${estimatedUsdRange})` : "";
     console.log(`  Estimated play spend: ${estimatedCreditsRange}${usdSuffix}`);
@@ -9643,29 +9678,54 @@ function printExtractions(label, entries) {
     console.log(`      - ${name}: ${expression}${pathSuffix}`);
   }
 }
+function singleLineText(value, maxLength = 260) {
+  if (typeof value !== "string") return "";
+  const text = value.replace(/\s+/g, " ").trim();
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 3).trimEnd()}...`;
+}
+function listedToolDescription(tool) {
+  const record = tool;
+  return singleLineText(record.bestFor ?? record.best_for ?? tool.description);
+}
+function formatListedToolCost(tool) {
+  const record = tool;
+  const pricing = recordField(record, "pricing");
+  const displayText = stringField(pricing, "displayText", "display_text");
+  return displayText ? `Cost: ${displayText}` : "";
+}
 function printToolCost(input) {
-  const { cost, billingSource, deeplineCredits, deeplineUsdPerPricingUnit } = input;
-  if (!cost) return false;
-  const pricingModel = typeof cost.pricingModel === "string" ? cost.pricingModel : typeof cost.pricing_model === "string" ? cost.pricing_model : "";
-  const billingMode = typeof cost.billingMode === "string" ? cost.billingMode : typeof cost.billing_mode === "string" ? cost.billing_mode : "";
-  const providerPrice = typeof cost.providerPricePerPricingModel === "number" ? cost.providerPricePerPricingModel : null;
-  if (pricingModel === "fixed" && providerPrice === 0) {
-    console.log("  Cost: free");
-    return true;
-  }
+  const { pricing, cost, billingSource, deeplineCredits, deeplineUsdPerPricingUnit } = input;
   if (billingSource === "own_provider_credentials") {
     console.log("  Cost: free through Deepline");
     return true;
   }
-  if (pricingModel && billingMode && deeplineCredits !== null) {
+  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)}` : "";
-    console.log(`  Cost: ${formatDecimal(deeplineCredits)} Deepline credits${usdText} per ${unit} (${billingMode})`);
+    const billingSuffix = billingMode ? ` (${billingMode})` : "";
+    console.log(`  Cost: ${formatDecimal(deeplineCredits)} Deepline credits${usdText} per ${unit}${billingSuffix}`);
     return true;
   }
-  if (pricingModel && billingMode && providerPrice !== null) {
-    const unit = pricingModel === "per_page" ? "page" : pricingModel === "per_result" ? "result" : "call";
-    console.log(`  Cost: ${formatDecimal(providerPrice)} provider credits per ${unit} (${billingMode})`);
+  const summary = stringField(pricing, "summary");
+  if (summary) {
+    console.log(`  Cost: ${summary}`);
     return true;
   }
   return false;

package/dist/cli/index.mjs

@@ -193,7 +193,7 @@ function resolveConfig(options) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.46";
+var SDK_VERSION = "0.1.48";
 var SDK_API_CONTRACT = "2026-05-stripe-promo-checkout";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
@@ -2777,8 +2777,10 @@ async function handleCheckout(options) {
 }
 async function handleRedeemCode(code, options) {
   const { http } = getAuthedHttpClient();
-  const payload = await http.post("/api/v2/billing/checkout/verify", { code });
-  const url = String(payload.url || "");
+  const payload = await http.post("/api/v2/billing/checkout", {
+    discountCode: code
+  });
+  const url = String(payload.url || payload.checkout_url || "");
   if (!options.json && !options.noOpen && url) openInBrowser(url);
   printCommandEnvelope({
     ...payload,
@@ -9219,11 +9221,16 @@ function extractSummaryFields(payload) {
 }
 
 // src/cli/commands/tools.ts
+var TOOL_COMMAND_TEMPLATES = {
+  describe: "deepline tools describe <toolId>",
+  execute: "deepline tools execute <toolId> --input '{...}'"
+};
 function toListedTool(tool) {
   if (isPlayLikeTool(tool)) {
     const playReference = playReferenceForTool(tool);
     return {
       ...tool,
+      description: listedToolDescription(tool),
       id: tool.toolId,
       type: "play",
       executeCommand: `deepline plays run ${playReference} --input '{...}' --watch`
@@ -9231,6 +9238,7 @@ function toListedTool(tool) {
   }
   return {
     ...tool,
+    description: listedToolDescription(tool),
     id: tool.toolId,
     type: "tool",
     executeCommand: `deepline tools execute ${tool.toolId}`
@@ -9243,14 +9251,29 @@ async function listTools(args) {
     sections: [
       {
         title: `${items.length} tools available:`,
-        lines: items.flatMap((item) => {
+        lines: items.map((item) => {
           const cats = item.categories.length ? ` [${item.categories.join(", ")}]` : "";
-          return [`${item.toolId}${cats}`, `  ${item.description}`];
+          const pricing = formatListedToolCost(item);
+          return `${item.toolId}${cats} - ${item.description}${pricing ? ` - ${pricing}` : ""}`;
         })
+      },
+      {
+        title: "next",
+        lines: [
+          "Run `deepline tools describe <toolId>` before executing a tool."
+        ]
       }
     ]
   };
-  printCommandEnvelope({ tools: items, count: items.length, render }, { json: argsWantJson(args) });
+  printCommandEnvelope(
+    {
+      tools: items,
+      count: items.length,
+      commandTemplates: TOOL_COMMAND_TEMPLATES,
+      render
+    },
+    { json: argsWantJson(args) }
+  );
   return 0;
 }
 async function searchTools(queryInput, options = {}) {
@@ -9468,8 +9491,22 @@ async function getTool(args) {
 }
 function toolMetadataJsonForDescribe(tool, requestedToolId) {
   const toolId = String(tool.toolId || requestedToolId);
+  const {
+    cost: _cost,
+    deeplineCreditsPerPricingUnit: _deeplineCreditsPerPricingUnit,
+    deeplineUsdPerPricingUnit: _deeplineUsdPerPricingUnit,
+    deeplineUsdPerCredit: _deeplineUsdPerCredit,
+    deeplinePricingSummary: _deeplinePricingSummary,
+    deeplinePricingDetails: _deeplinePricingDetails,
+    deepline_credits_per_pricing_unit: _snakeDeeplineCreditsPerPricingUnit,
+    deepline_usd_per_pricing_unit: _snakeDeeplineUsdPerPricingUnit,
+    deepline_usd_per_credit: _snakeDeeplineUsdPerCredit,
+    deepline_pricing_summary: _snakeDeeplinePricingSummary,
+    deepline_pricing_details: _snakeDeeplinePricingDetails,
+    ...publicTool
+  } = tool;
   return {
-    ...tool,
+    ...publicTool,
     toolId,
     provider: tool.provider,
     displayName: tool.displayName,
@@ -9488,9 +9525,9 @@ function printToolDetails(tool, requestedToolId) {
   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 deeplineUsdPerCredit = numberField(tool, "deeplineUsdPerCredit", "deepline_usd_per_credit");
   const billingSource = stringField(tool, "billingSource", "billing_source");
   const billingSourceLabel = stringField(tool, "billingSourceLabel", "billing_source_label");
   const estimatedCreditsRange = stringField(tool, "estimatedCreditsRange", "estimated_credits_range");
@@ -9515,6 +9552,7 @@ function printToolDetails(tool, requestedToolId) {
     console.log(`    ${tool.categories.join(", ")}`);
   }
   const printedCost = printToolCost({
+    pricing,
     cost,
     billingSource,
     deeplineCredits,
@@ -9526,9 +9564,6 @@ function printToolDetails(tool, requestedToolId) {
   if (billingSourceLabel) {
     console.log(`  Billing source: ${billingSourceLabel}`);
   }
-  if (typeof deeplineUsdPerCredit === "number") {
-    console.log(`  Deepline rate: $${deeplineUsdPerCredit.toFixed(2)} per credit`);
-  }
   if (estimatedCreditsRange) {
     const usdSuffix = estimatedUsdRange ? ` (~${estimatedUsdRange})` : "";
     console.log(`  Estimated play spend: ${estimatedCreditsRange}${usdSuffix}`);
@@ -9630,29 +9665,54 @@ function printExtractions(label, entries) {
     console.log(`      - ${name}: ${expression}${pathSuffix}`);
   }
 }
+function singleLineText(value, maxLength = 260) {
+  if (typeof value !== "string") return "";
+  const text = value.replace(/\s+/g, " ").trim();
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 3).trimEnd()}...`;
+}
+function listedToolDescription(tool) {
+  const record = tool;
+  return singleLineText(record.bestFor ?? record.best_for ?? tool.description);
+}
+function formatListedToolCost(tool) {
+  const record = tool;
+  const pricing = recordField(record, "pricing");
+  const displayText = stringField(pricing, "displayText", "display_text");
+  return displayText ? `Cost: ${displayText}` : "";
+}
 function printToolCost(input) {
-  const { cost, billingSource, deeplineCredits, deeplineUsdPerPricingUnit } = input;
-  if (!cost) return false;
-  const pricingModel = typeof cost.pricingModel === "string" ? cost.pricingModel : typeof cost.pricing_model === "string" ? cost.pricing_model : "";
-  const billingMode = typeof cost.billingMode === "string" ? cost.billingMode : typeof cost.billing_mode === "string" ? cost.billing_mode : "";
-  const providerPrice = typeof cost.providerPricePerPricingModel === "number" ? cost.providerPricePerPricingModel : null;
-  if (pricingModel === "fixed" && providerPrice === 0) {
-    console.log("  Cost: free");
-    return true;
-  }
+  const { pricing, cost, billingSource, deeplineCredits, deeplineUsdPerPricingUnit } = input;
   if (billingSource === "own_provider_credentials") {
     console.log("  Cost: free through Deepline");
     return true;
   }
-  if (pricingModel && billingMode && deeplineCredits !== null) {
+  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)}` : "";
-    console.log(`  Cost: ${formatDecimal(deeplineCredits)} Deepline credits${usdText} per ${unit} (${billingMode})`);
+    const billingSuffix = billingMode ? ` (${billingMode})` : "";
+    console.log(`  Cost: ${formatDecimal(deeplineCredits)} Deepline credits${usdText} per ${unit}${billingSuffix}`);
     return true;
   }
-  if (pricingModel && billingMode && providerPrice !== null) {
-    const unit = pricingModel === "per_page" ? "page" : pricingModel === "per_result" ? "result" : "call";
-    console.log(`  Cost: ${formatDecimal(providerPrice)} provider credits per ${unit} (${billingMode})`);
+  const summary = stringField(pricing, "summary");
+  if (summary) {
+    console.log(`  Cost: ${summary}`);
     return true;
   }
   return false;

package/dist/index.d.mts

@@ -221,6 +221,22 @@ interface CustomerDbQueryResult {
     columns: CustomerDbColumn[];
     rows: unknown[];
 }
+interface ToolPricingSummary {
+    /** User-facing pricing text for quick discovery displays. */
+    displayText: string | null;
+    /** User-facing unit the price applies to. */
+    unit: 'call' | 'result' | 'page' | 'usage' | null;
+    /** Deepline credits charged per unit, when statically knowable. */
+    creditsPerUnit: number | null;
+    /** USD equivalent charged per unit, when statically knowable. */
+    usdPerUnit: number | null;
+    /** Currency for `usdPerUnit`. */
+    currency: 'USD';
+    /** Short user-facing pricing summary for variable pricing. */
+    summary: string | null;
+    /** Additional user-facing pricing notes. */
+    details: string[];
+}
 /**
  * Summary definition of a tool, returned by {@link DeeplineClient.listTools}.
  *
@@ -255,6 +271,8 @@ interface ToolDefinition {
     inputSchema?: Record<string, unknown>;
     /** JSON Schema describing the tool's output shape. */
     outputSchema?: Record<string, unknown>;
+    /** User-facing pricing summary. Internal provider/settlement costs are intentionally omitted. */
+    pricing?: ToolPricingSummary | null;
     /** Copyable play-runtime guidance for V2 tool execution results. */
     usageGuidance?: {
         execute?: string;
@@ -327,6 +345,10 @@ interface ToolSearchResult {
     search_mode?: 'v1' | 'v2';
     search_fallback_to_category?: boolean;
     omitted_plays_hint?: string;
+    commandTemplates?: {
+        describe?: string;
+        execute?: string;
+    };
     render?: {
         sections?: Array<{
             title: string;
@@ -357,11 +379,11 @@ interface ToolMetadata extends ToolDefinition {
     asyncGetAction?: string | null;
     /** Known failure scenarios and their expected handling. */
     failureMode?: Record<string, unknown> | null;
-    /** Provider-side pricing structure. */
+    /** Sanitized pricing model for describe metadata. Provider internal prices are intentionally omitted. */
     cost?: Record<string, unknown> | null;
-    /** How many Deepline credits map to one provider pricing unit. */
+    /** Deepline credits charged for one user-visible pricing unit. */
     deeplineCreditsPerPricingUnit?: number | null;
-    /** Whether cost is billed by the provider or by Deepline. */
+    /** Whether the customer pays with Deepline credits or their own connected account. */
     billingSource?: string;
     /** Display label for the billing source. */
     billingSourceLabel?: string;
@@ -1511,7 +1533,7 @@ declare class DeeplineClient {
     }>;
 }
 
-declare const SDK_VERSION = "0.1.46";
+declare const SDK_VERSION = "0.1.48";
 declare const SDK_API_CONTRACT = "2026-05-stripe-promo-checkout";
 
 /**
@@ -1829,6 +1851,7 @@ type ToolExecutionRequest = {
     tool: string;
     input: Record<string, unknown>;
     description?: string;
+    staleAfterSeconds?: number;
 };
 type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number) => Value | Promise<Value>;
 type ConditionalStepResolver<Row, Value, Else = null> = {
@@ -1912,7 +1935,10 @@ type CsvOptions = {
  *   const enriched = await ctx
  *     .map('companies', [{ domain: 'a.com' }, { domain: 'b.com' }])
  *     .step('company', (row, rowCtx) =>
- *       rowCtx.tool('company_search', 'test_company_search', { domain: row.domain }, {
+ *       rowCtx.tools.execute({
+ *         id: 'company_search',
+ *         tool: 'test_company_search',
+ *         input: { domain: row.domain },
  *         description: 'Look up company details by domain.',
  *       }))
  *     .run({ description: 'Look up company details.' });
@@ -1973,30 +1999,30 @@ interface DeeplinePlayRuntimeContext {
      *
      * @example Single tool per row
      * ```typescript
-   * const results = await ctx
-   *   .map('companies', leads)
-   *   .step('company', (row, ctx) =>
-   *     ctx.tools.execute({
-   *       id: 'company_search',
-   *       tool: 'test_company_search',
-   *       input: { domain: row.domain },
-   *       description: 'Look up company details by domain.',
-   *     }))
+     * const results = await ctx
+     *   .map('companies', leads)
+     *   .step('company', (row, ctx) =>
+     *     ctx.tools.execute({
+     *       id: 'company_search',
+     *       tool: 'test_company_search',
+     *       input: { domain: row.domain },
+     *       description: 'Look up company details by domain.',
+     *     }))
      *   .run({ description: 'Look up companies.' });
      * // [{ domain: 'stripe.com', company: { name: 'Stripe', ... } }, ...]
      * ```
      *
      * @example Multiple columns with pre/post logic
      * ```typescript
-   * const results = await ctx
-   *   .map('leads', leads)
-   *   .step('company', (row, ctx) =>
-   *     ctx.tools.execute({
-   *       id: 'company_search',
-   *       tool: 'test_company_search',
-   *       input: { domain: row.domain },
-   *       description: 'Look up company details by domain.',
-   *     }))
+     * const results = await ctx
+     *   .map('leads', leads)
+     *   .step('company', (row, ctx) =>
+     *     ctx.tools.execute({
+     *       id: 'company_search',
+     *       tool: 'test_company_search',
+     *       input: { domain: row.domain },
+     *       description: 'Look up company details by domain.',
+     *     }))
      *   .step('score', (row) =>
      *     row.company?.employeeCount > 100 ? 'enterprise' : 'smb')
      *   .run({ description: 'Enrich leads.' });
@@ -2013,22 +2039,19 @@ interface DeeplinePlayRuntimeContext {
          * @param request.input - Tool-specific input parameters
          * @returns The tool's output
          */
-        execute<TOutput = LoosePlayObject>(request: ToolExecutionRequest): Promise<ToolExecuteResult<TOutput>>;
+        execute<TOutput = LoosePlayObject>(request: ToolExecutionRequest & {
+            staleAfterSeconds?: number;
+        }): Promise<ToolExecuteResult<TOutput>>;
     };
-    /**
-     * Execute a single tool by stable step key and tool ID.
-     *
-     * Shorthand for `ctx.tools.execute(...)`; this is the preferred spelling in
-     * row-level step programs.
-     */
-    tool<TOutput = LoosePlayObject>(key: string, toolId: string, input: Record<string, unknown>, options?: {
-        description?: string;
-    }): Promise<ToolExecuteResult<TOutput>>;
     runSteps<TInput extends Record<string, unknown>, TOutput>(program: StepProgram<TInput, any, TOutput>, input: TInput, options?: {
         description?: string;
     }): Promise<TOutput>;
-    step<T>(id: string, run: () => T | Promise<T>): Promise<T>;
-    fetch(key: string, url: string | URL, init?: RequestInit): Promise<{
+    step<T>(id: string, run: () => T | Promise<T>, options?: {
+        staleAfterSeconds?: number;
+    }): Promise<T>;
+    fetch(key: string, url: string | URL, init?: RequestInit, options?: {
+        staleAfterSeconds?: number;
+    }): Promise<{
         ok: boolean;
         status: number;
         statusText: string;
@@ -2039,6 +2062,7 @@ interface DeeplinePlayRuntimeContext {
     }>;
     runPlay(key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options: {
         description?: string;
+        staleAfterSeconds?: number;
     }): Promise<Record<string, unknown>>;
     /**
      * Emit a log line visible in `play tail` and the play's progress logs.