deepline 0.1.46 → 0.1.48

package/dist/repo/apps/play-runner-workers/src/runtime/receipts.ts

@@ -48,6 +48,7 @@ export type WorkerRuntimeReceiptAction =
 type RuntimeReceiptContext = {
   baseUrl: string;
   executorToken: string;
+  orgId?: string | null;
   playName: string;
   runId: string;
   key: string;
@@ -59,11 +60,11 @@ type RuntimeReceiptContext = {
 };
 
 function scopedReceiptKey(input: {
+  orgId?: string | null;
   playName: string;
-  runId: string;
   key: string;
 }): string {
-  return `run:${input.runId}:play:${input.playName}:${input.key}`;
+  return `ctx:${input.orgId?.trim() || 'org'}:${input.playName.trim() || 'play'}:${input.key}`;
 }
 
 function receiptOutput<T>(receipt: WorkerRuntimeReceipt): T {
@@ -74,13 +75,21 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function runningReceiptError(key: string, receipt: WorkerRuntimeReceipt): Error {
+  return new Error(
+    `Runtime receipt ${key} is already running for run ${receipt.runId ?? 'unknown'}.`,
+  );
+}
+
 export async function runWorkerRuntimeReceiptBoundary<T>(
   input: RuntimeReceiptContext & {
     execute: () => Promise<T> | T;
   },
 ): Promise<T> {
   const key = scopedReceiptKey(input);
-  const existing = await input.postRuntimeApi(input.baseUrl, input.executorToken, {
+  const postRuntimeReceiptAction = (body: WorkerRuntimeReceiptAction) =>
+    input.postRuntimeApi(input.baseUrl, input.executorToken, body);
+  const existing = await postRuntimeReceiptAction({
     action: 'get_runtime_step_receipt',
     playName: input.playName,
     runId: input.runId,
@@ -93,46 +102,67 @@ export async function runWorkerRuntimeReceiptBoundary<T>(
     return receiptOutput<T>(existing.receipt);
   }
 
-  const claimed = await input.postRuntimeApi(input.baseUrl, input.executorToken, {
+  const claimed = await postRuntimeReceiptAction({
     action: 'claim_runtime_step_receipt',
     playName: input.playName,
     runId: input.runId,
     key,
   });
   if (!claimed.receipt) {
+    const latest = await postRuntimeReceiptAction({
+      action: 'get_runtime_step_receipt',
+      playName: input.playName,
+      runId: input.runId,
+      key,
+    });
     if (
-      existing.receipt?.status === 'running' &&
-      existing.receipt.runId !== input.runId
+      latest.receipt?.status === 'completed' ||
+      latest.receipt?.status === 'skipped'
     ) {
-      throw new Error(
-        `Runtime receipt ${key} is already running for run ${existing.receipt.runId ?? 'unknown'}.`,
-      );
+      return receiptOutput<T>(latest.receipt);
     }
-    if (existing.receipt?.status === 'failed') {
+    if (latest.receipt?.status === 'running') {
+      throw runningReceiptError(key, latest.receipt);
+    }
+    if (latest.receipt?.status === 'failed') {
       throw new Error(
-        `Runtime receipt ${key} is failed and could not be claimed: ${existing.receipt.error ?? 'unknown error'}`,
+        `Runtime receipt ${key} is failed and could not be claimed: ${latest.receipt.error ?? 'unknown error'}`,
       );
     }
+    throw new Error(
+      `Runtime receipt ${key} claim did not return execution ownership.`,
+    );
   }
 
+  let output: T;
   try {
-    const output = await input.execute();
-    await input.postRuntimeApi(input.baseUrl, input.executorToken, {
-      action: 'complete_runtime_step_receipt',
-      playName: input.playName,
-      runId: input.runId,
-      key,
-      output,
-    });
-    return output;
+    output = await input.execute();
   } catch (error) {
-    await input.postRuntimeApi(input.baseUrl, input.executorToken, {
+    const failed = await postRuntimeReceiptAction({
       action: 'fail_runtime_step_receipt',
       playName: input.playName,
       runId: input.runId,
       key,
       error: errorMessage(error),
     });
+    if (!failed.receipt) {
+      throw new Error(
+        `Runtime receipt ${key} execution failed and failed receipt could not be persisted: ${errorMessage(error)}`,
+      );
+    }
     throw error;
   }
+  const completed = await postRuntimeReceiptAction({
+    action: 'complete_runtime_step_receipt',
+    playName: input.playName,
+    runId: input.runId,
+    key,
+    output,
+  });
+  if (!completed.receipt) {
+    throw new Error(
+      `Runtime receipt ${key} execution completed but completed receipt could not be persisted.`,
+    );
+  }
+  return output;
 }

package/dist/repo/sdk/src/play.ts

@@ -166,6 +166,7 @@ export type ToolExecutionRequest = {
   tool: string;
   input: Record<string, unknown>;
   description?: string;
+  staleAfterSeconds?: number;
 };
 
 export type StepResolver<Row, Value> = (
@@ -297,7 +298,10 @@ export 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.' });
@@ -362,30 +366,30 @@ export 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.' });
@@ -407,31 +411,24 @@ export interface DeeplinePlayRuntimeContext {
      * @returns The tool's output
      */
     execute<TOutput = LoosePlayObject>(
-      request: ToolExecutionRequest,
+      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>;
+  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;
@@ -445,7 +442,7 @@ export interface DeeplinePlayRuntimeContext {
     key: string,
     playRef: string | PlayReferenceLike,
     input: Record<string, unknown>,
-    options: { description?: string },
+    options: { description?: string; staleAfterSeconds?: number },
   ): Promise<Record<string, unknown>>;
 
   /**
@@ -944,11 +941,9 @@ export class DeeplineContext {
         toolId: string,
         input: Record<string, unknown>,
       ): Promise<ToolExecuteResult> => {
-        const response = await this.client.executeTool(
-          toolId,
-          input,
-          { includeToolMetadata: true },
-        );
+        const response = await this.client.executeTool(toolId, input, {
+          includeToolMetadata: true,
+        });
         return toolExecutionEnvelopeToResult(toolId, response);
       },
     };
@@ -1150,9 +1145,7 @@ function toolExecutionEnvelopeToResult(
           ? toolMetadata.toolId
           : fallbackToolId,
       extractors: extractorDescriptorRecord(toolMetadata.extractors),
-      targetGetters: stringArrayRecord(
-        toolMetadata.targetGetters,
-      ),
+      targetGetters: stringArrayRecord(toolMetadata.targetGetters),
       listExtractorPaths: stringArray(toolMetadata.listExtractorPaths),
       listIdentityGetters: stringArrayRecord(toolMetadata.listIdentityGetters),
     },

package/dist/repo/sdk/src/plays/harness-stub.ts

@@ -53,7 +53,7 @@ export type HarnessBinding = PlayHarnessRpc;
  *
  * Why a module-level holder instead of threading the binding through
  * every call site: most leaf-call sites are deep inside SDK utilities
- * (`ctx.tool`, `ctx.csv`, etc.) and threading a binding everywhere would
+ * (`ctx.tools.execute`, `ctx.csv`, etc.) and threading a binding everywhere would
  * be a structural mess. A single set-once holder, set very early in the
  * worker's lifecycle, gives us clean call sites without sacrificing
  * isolation — each per-play Worker is its own isolate, so the holder is

package/dist/repo/sdk/src/types.ts

@@ -69,6 +69,23 @@ export interface CustomerDbQueryResult {
   rows: unknown[];
 }
 
+export 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}.
  *
@@ -103,6 +120,8 @@ export 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;
@@ -177,6 +196,10 @@ export 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;
@@ -208,11 +231,11 @@ export 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;

package/dist/repo/sdk/src/version.ts

@@ -1,2 +1,2 @@
-export const SDK_VERSION = "0.1.46";
+export const SDK_VERSION = "0.1.48";
 export const SDK_API_CONTRACT = "2026-05-stripe-promo-checkout";

package/dist/repo/sdk/src/worker-play-entry.ts

@@ -11,7 +11,6 @@
 import type {
   ConditionalStepResolver,
   DefinePlayConfig,
-  DeeplineNamedPlay,
   DeeplinePlayRuntimeContext,
   DefinedPlay,
   PlayBindings,
@@ -57,9 +56,11 @@ type PlayMetadata = {
   billing?: PlayBindings['billing'];
 };
 
-class WorkerConditionalStepResolver<Row, Value, ElseValue>
-  implements ConditionalStepResolver<Row, Value, ElseValue>
-{
+class WorkerConditionalStepResolver<
+  Row,
+  Value,
+  ElseValue,
+> implements ConditionalStepResolver<Row, Value, ElseValue> {
   readonly kind = 'conditional' as const;
 
   constructor(
@@ -75,9 +76,11 @@ class WorkerConditionalStepResolver<Row, Value, ElseValue>
   }
 }
 
-class WorkerStepProgram<Input, Output, ReturnValue>
-  implements StepProgram<Input, Output, ReturnValue>
-{
+class WorkerStepProgram<Input, Output, ReturnValue> implements StepProgram<
+  Input,
+  Output,
+  ReturnValue
+> {
   readonly kind = 'steps' as const;
   declare readonly __inputType?: (input: Input) => void;
 
@@ -94,7 +97,7 @@ class WorkerStepProgram<Input, Output, ReturnValue>
       | StepProgramResolver<Output, Value>,
   ): StepProgram<Input, Output & Record<Name, Value>, ReturnValue> {
     if (!name.trim()) {
-      throw new Error('steps().step(name, ...) requires a non-empty step name.');
+      throw new Error('Step name required.');
     }
     return new WorkerStepProgram(
       [
@@ -118,26 +121,6 @@ class WorkerStepProgram<Input, Output, ReturnValue>
   }
 }
 
-function createUnavailableNamedPlayHandle<TInput, TOutput extends PlayReturnObject>(
-  name: string,
-): DeeplineNamedPlay<TInput, TOutput> {
-  const unavailable = () => {
-    throw new Error(
-      `definePlay("${name}") remote lifecycle methods are unavailable inside workers_edge play execution. Use ctx.runPlay(...) for runtime composition.`,
-    );
-  };
-  return {
-    name,
-    get: unavailable,
-    runs: unavailable,
-    versions: unavailable,
-    publish: unavailable,
-    clearHistory: unavailable,
-    run: unavailable,
-    runSync: unavailable,
-  };
-}
-
 export function steps<TInput>(): StepProgram<TInput, TInput, TInput> {
   return new WorkerStepProgram<TInput, TInput, TInput>([]);
 }
@@ -153,9 +136,7 @@ export function defineInput<TInput>(
   schema: Record<string, unknown>,
 ): PlayInputContract<TInput> {
   if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
-    throw new Error(
-      'defineInput<T>(schema) requires a JSON-schema-like object.',
-    );
+    throw new Error('defineInput schema must be an object');
   }
   return { schema };
 }
@@ -196,12 +177,10 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
   const name = config.name;
   const fn = config.fn;
   if (typeof fn !== 'function') {
-    throw new Error('definePlay(...) requires an async run function.');
+    throw new Error('definePlay run must be async');
   }
   if (name.includes('/')) {
-    throw new Error(
-      'definePlay(name, ...) play names cannot contain "/". Slash is reserved for qualified references like "prebuilt/example" or "self/example".',
-    );
+    throw new Error('Play name cannot contain /');
   }
   const normalizedName = name
     .trim()
@@ -210,14 +189,10 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
     .replace(/^_+|_+$/g, '')
     .toLowerCase();
   if (!normalizedName) {
-    throw new Error(
-      'definePlay(name, ...) requires a play name with at least one letter or number. Use only letters, numbers, underscores, or hyphens.',
-    );
+    throw new Error('Play name required');
   }
   if (normalizedName.length > 63) {
-    throw new Error(
-      `definePlay("${name}", ...) is too long after normalization (${normalizedName.length}/63). Shorten the play name to 63 characters or fewer. Normalized value: "${normalizedName}".`,
-    );
+    throw new Error('Play name >63');
   }
 
   const metadata: PlayMetadata = {
@@ -230,42 +205,17 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
 
   Object.defineProperty(play, PLAY_METADATA_SYMBOL, {
     value: metadata,
-    enumerable: false,
-    configurable: false,
-    writable: false,
   });
   Object.defineProperty(play, 'playName', {
     value: name,
     enumerable: true,
-    configurable: false,
-    writable: false,
   });
   Object.defineProperty(play, 'bindings', {
     value: config.bindings,
     enumerable: true,
-    configurable: false,
-    writable: false,
   });
 
-  const handle = createUnavailableNamedPlayHandle<TInput, TOutput>(name);
-  for (const key of [
-    'name',
-    'get',
-    'runs',
-    'versions',
-    'publish',
-    'clearHistory',
-    'run',
-    'runSync',
-  ] as const) {
-    Object.defineProperty(play, key, {
-      value: handle[key],
-      enumerable: false,
-      configurable: false,
-      writable: false,
-    });
-  }
-
+  Object.defineProperty(play, 'name', { value: name });
   return play;
 }
 

package/dist/repo/shared_libs/plays/row-identity.ts

@@ -38,7 +38,7 @@ function stableValue(value: unknown): unknown {
   return value;
 }
 
-function stableStringify(value: unknown): string {
+export function stableStringify(value: unknown): string {
   return JSON.stringify(stableValue(value));
 }
 
@@ -46,7 +46,7 @@ function rightRotate32(value: number, bits: number): number {
   return (value >>> bits) | (value << (32 - bits));
 }
 
-function sha256Hex(input: string): string {
+export function sha256Hex(input: string): string {
   const bytes = Array.from(new TextEncoder().encode(input));
   const bitLength = bytes.length * 8;
   bytes.push(0x80);
@@ -232,20 +232,6 @@ export function resolveStaleMapTableNamespace(
   return `${prefix}_${digest}`;
 }
 
-export function maxArtifactTableNamespaceLength(
-  playName?: string | null,
-): number {
-  if (!playName?.trim()) {
-    return POSTGRES_IDENTIFIER_MAX_LENGTH;
-  }
-
-  const normalizedPlayName = normalizePlayNameForSheet(playName);
-  return Math.max(
-    1,
-    POSTGRES_IDENTIFIER_MAX_LENGTH - normalizedPlayName.length - 1,
-  );
-}
-
 export function validatePlaySheetTableName(
   playName: string,
   tableNamespace: string,
@@ -263,71 +249,37 @@ export function validatePlaySheetTableName(
   return resolved;
 }
 
-export function resolvePlayRunTableNamespace(
-  tableNamespace: string,
-  _input?: Record<string, unknown> | null,
-  _options?: {
-    playName?: string | null;
-  },
-): string {
-  return normalizeTableNamespace(tableNamespace);
-}
-
 export function derivePlayRowIdentity(
   row: Record<string, unknown>,
   tableNamespace: string,
-  logicFingerprint?: string | null,
 ): string {
   return deriveDerivedOutputIdentity({
     inputItem: row,
     operationNamespace: tableNamespace,
-    logicFingerprint,
   });
 }
 
 export function deriveDerivedOutputIdentity(input: {
   inputItem: Record<string, unknown>;
   operationNamespace: string;
-  logicFingerprint?: string | null;
 }): string {
-  const normalizedNamespace = normalizeTableNamespace(
-    input.operationNamespace,
-  );
+  const normalizedNamespace = normalizeTableNamespace(input.operationNamespace);
   const canonicalRow = stableStringify(input.inputItem);
-  const fingerprint = input.logicFingerprint?.trim()
-    ? `\nlogic:${input.logicFingerprint.trim()}`
-    : '';
-  const digest = sha256Hex(
-    `${normalizedNamespace}${fingerprint}\n${canonicalRow}`,
-  );
+  const digest = sha256Hex(`${normalizedNamespace}\n${canonicalRow}`);
   return `${normalizedNamespace}:${digest}`;
 }
 
 export function deriveToolRequestIdentity(input: {
   toolId: string;
   requestInput: Record<string, unknown>;
-  effectiveAccountContext?: string | null;
-  toolContractRevision?: string | number | null;
-  reuseSafetyPolicy?: string | null;
 }): string {
   const toolId = input.toolId.trim();
   if (!toolId) {
     throw new Error('Tool request identity requires a non-empty tool id.');
   }
-  const accountContext =
-    input.effectiveAccountContext?.trim() || 'default_account_context';
-  const contractRevision =
-    input.toolContractRevision == null
-      ? 'default_tool_contract'
-      : String(input.toolContractRevision).trim() || 'default_tool_contract';
-  const reuseSafetyPolicy =
-    input.reuseSafetyPolicy?.trim() || 'default_reuse_policy';
   const digest = sha256Hex(
     stableStringify({
-      accountContext,
       requestInput: input.requestInput,
-      reuseSafetyPolicy,
-      toolContractRevision: contractRevision,
       toolId,
     }),
   );
@@ -344,14 +296,8 @@ export function deriveToolRequestIdentity(input: {
 export function derivePlayRowIdentityFromKey(
   key: string,
   tableNamespace: string,
-  logicFingerprint?: string | null,
 ): string {
   const normalizedNamespace = normalizeTableNamespace(tableNamespace);
-  const fingerprint = logicFingerprint?.trim()
-    ? `\nlogic:${logicFingerprint.trim()}`
-    : '';
-  const digest = sha256Hex(`${normalizedNamespace}${fingerprint}\nkey:${key}`);
+  const digest = sha256Hex(`${normalizedNamespace}\nkey:${key}`);
   return `${normalizedNamespace}:${digest}`;
 }
-
-export const normalizeMapKeyNamespace = normalizeTableNamespace;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {