deepline 0.1.302 → 0.1.304

package/dist/bundling-sources/sdk/src/errors.ts

@@ -5,38 +5,28 @@ import {
   brandAsProviderTransientError,
   brandAsToolExecutionError,
   isProviderTransientFailure,
+  type ProviderTransientErrorCategory,
+  type ToolExecutionErrorCategory,
+  type ToolExecutionFailureV1,
+  type ToolExecutionErrorOrigin,
   type ToolExecutionErrorOptions,
+  type ToolExecutionNetworkKind,
+  type ToolExecutionNetworkScope,
 } from '../../shared_libs/tool-execution-error.js';
 
 export {
   DeeplineError,
   ProviderTransientError,
   ToolExecutionError,
+  type ProviderTransientErrorCategory,
+  type ToolExecutionErrorCategory,
+  type ToolExecutionFailureV1,
+  type ToolExecutionErrorOrigin,
   type ToolExecutionErrorOptions,
+  type ToolExecutionNetworkKind,
+  type ToolExecutionNetworkScope,
 } from '../../shared_libs/tool-execution-error.js';
 
-/**
- * Base error class for all Deepline SDK errors.
- *
- * Every error thrown by the SDK extends this class, so you can catch all
- * Deepline-specific errors with a single `catch (e) { if (e instanceof DeeplineError) }`.
- *
- * @example
- * ```typescript
- * import { DeeplineClient, DeeplineError, AuthError } from 'deepline';
- *
- * const client = new DeeplineClient();
- * try {
- *   await client.executeTool('dropleads_search_people', { query: 'cto' });
- * } catch (err) {
- *   if (err instanceof AuthError) {
- *     console.error('Bad API key — run: deepline auth register');
- *   } else if (err instanceof DeeplineError) {
- *     console.error(`API error ${err.statusCode}: ${err.message}`);
- *   }
- * }
- * ```
- */
 /**
  * Thrown when the API rejects the request due to an invalid or missing API key.
  *
@@ -58,8 +48,11 @@ export {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 090
  */
 export class AuthError extends DeeplineError {
+  /** Constructed by the SDK when Deepline rejects the caller's credentials. */
   constructor(message = 'Authentication failed. Check your DEEPLINE_API_KEY.') {
     super(message, 401, 'AUTH_ERROR');
     this.name = 'AuthError';
@@ -88,11 +81,14 @@ export class AuthError extends DeeplineError {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 100
  */
 export class RateLimitError extends DeeplineError {
   /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
   public retryAfterMs: number;
 
+  /** Constructed by the SDK after exhausting HTTP-level rate-limit retries. */
   constructor(retryAfterMs = 5000, message?: string) {
     super(
       message ?? `Rate limited. Retry after ${retryAfterMs}ms.`,
@@ -109,19 +105,38 @@ export class RateLimitError extends DeeplineError {
  * structured ToolExecutionError ontology. JavaScript has one prototype chain,
  * so this class extends RateLimitError and carries ToolExecutionError's stable
  * cross-bundle brand.
+ *
+ * This class appears in external SDK calls after HTTP 429 retries are
+ * exhausted. It also satisfies `instanceof ToolExecutionError` and, for a
+ * provider-owned rate limit, `instanceof ProviderTransientError`. Authored
+ * Plays should use `ProviderTransientError`; they do not need this
+ * compatibility class.
+ *
+ * @sdkReference errors 110
  */
 export class ToolRateLimitError extends RateLimitError {
+  /** Public tool id passed to `tools.execute`. */
   readonly toolId: string;
+  /** Provider responsible for the operation, or `null`. */
   readonly provider: string | null;
+  /** Provider operation name, or `null`. */
   readonly operation: string | null;
+  /** Stable machine-readable failure code when one exists. */
   override readonly code: string | undefined;
+  /** Boundary responsible for the failure. */
   readonly origin: ToolExecutionError['origin'];
+  /** Stable reason family for policy and diagnostics. */
   readonly category: ToolExecutionError['category'];
+  /** Whether repeating the same semantic call is delivery-safe. */
   readonly retryable: boolean;
+  /** Provider or Deepline request id, or `null`. */
   readonly requestId: string | null;
+  /** Network failure kind, or `null` for non-network failures. */
   readonly networkKind: ToolExecutionError['networkKind'];
+  /** Network boundary that failed, or `null` for non-network failures. */
   readonly networkScope: ToolExecutionError['networkScope'];
 
+  /** Constructed by the SDK after a structured tool HTTP 429. */
   constructor(message: string, options: ToolExecutionErrorOptions) {
     super(options.retryAfterMs ?? 5_000, message);
     this.name = 'ToolRateLimitError';
@@ -162,8 +177,11 @@ export class ToolRateLimitError extends RateLimitError {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 120
  */
 export class ConfigError extends DeeplineError {
+  /** Construct a local SDK configuration failure. */
   constructor(message: string) {
     super(message, undefined, 'CONFIG_ERROR');
     this.name = 'ConfigError';

package/dist/bundling-sources/sdk/src/index.ts

@@ -130,7 +130,15 @@ export {
   ToolRateLimitError,
   ConfigError,
 } from './errors.js';
-export type { ToolExecutionErrorOptions } from './errors.js';
+export type {
+  ProviderTransientErrorCategory,
+  ToolExecutionErrorCategory,
+  ToolExecutionFailureV1,
+  ToolExecutionErrorOrigin,
+  ToolExecutionErrorOptions,
+  ToolExecutionNetworkKind,
+  ToolExecutionNetworkScope,
+} from './errors.js';
 
 // ——— Config ———
 export { resolveConfig, PROD_URL } from './config.js';

package/dist/bundling-sources/sdk/src/release.ts

@@ -157,7 +157,7 @@ export const SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: '0.1.302',
+  version: '0.1.304',
   contracts: {
     api: {
       name: 'sdk-http-api',

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -1644,7 +1644,7 @@ export class PlayContextImpl {
     tableNamespace: string | null,
     update: Omit<PlayRowUpdate, 'key'>,
   ): void {
-    assertNoSecretTaint(update, 'ctx.map row update');
+    assertNoSecretTaint(update, 'ctx.dataset row update');
     const rowScope = rowContext.getStore()?.mapScope;
     if (rowScope && key) {
       this.emitExecutionEvent({

package/dist/bundling-sources/shared_libs/play-runtime/tool-result-paths.ts

@@ -0,0 +1,15 @@
+/**
+ * Derive the public semantic accessor name from a declared list path.
+ *
+ * Keep this independent from path normalization: `result.data` may resolve to
+ * `toolResponse.raw`, but its public getter remains `extractedLists.data`.
+ */
+export function listNameFromDeclaredPath(path: string): string | null {
+  return (
+    String(path || '')
+      .split('.')
+      .filter(Boolean)
+      .at(-1)
+      ?.replace(/[^A-Za-z0-9_$]/g, '') || null
+  );
+}

package/dist/bundling-sources/shared_libs/play-runtime/tool-result-types.ts

@@ -42,6 +42,8 @@ export type ToolResultMetadata = {
   execution: ToolResultExecutionMetadata;
   targets: Record<string, ToolResultTargetMetadata>;
   lists: Record<string, ToolResultListMetadata>;
+  /** Original declarations preserve semantic accessor names across replay. */
+  listExtractorPaths?: readonly string[];
   extractors?: Record<string, ToolResultExtractorDescriptor>;
 };
 
@@ -130,6 +132,8 @@ export type ToolExecuteResultBase<
         keys: Record<string, string>;
       }
     >;
+    /** Original declarations preserve semantic accessor names across replay. */
+    listExtractorPaths?: readonly string[];
   };
 };
 

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -47,6 +47,7 @@ import {
   type SerializedPlayDataset,
 } from '../plays/dataset';
 import { normalizeTableNamespace, sha256Hex } from '../plays/row-identity';
+import { listNameFromDeclaredPath } from './tool-result-paths';
 
 type PathSegment = string | number | '*';
 
@@ -744,43 +745,35 @@ function resolveListRows(
     { path: string; rows: Record<string, unknown>[] }
   > = {};
   for (const rawPath of listExtractorPaths ?? []) {
+    const listName = listNameFromDeclaredPath(rawPath);
+    if (!listName) continue;
     const path = normalizeResultPath(rawPath);
     if (!path) continue;
     const candidates = [...candidateResultPaths(rawPath)].filter(
       (candidate, index, all) => candidate && all.indexOf(candidate) === index,
     );
-    let resolvedPath: string | null = null;
-    let rows: Record<string, unknown>[] | null = null;
+    let resolved: { path: string; rows: Record<string, unknown>[] } | null =
+      null;
     let emptyMatch: { path: string; rows: Record<string, unknown>[] } | null =
       null;
     for (const candidate of candidates) {
-      rows = normalizeRows(getAtPath(result, candidate));
-      if (!rows) {
+      const candidateRows = normalizeRows(getAtPath(result, candidate));
+      if (!candidateRows) {
         continue;
       }
-      if (rows.length > 0) {
-        resolvedPath = candidate;
+      if (candidateRows.length > 0) {
+        resolved = { path: candidate, rows: candidateRows };
         break;
       }
-      emptyMatch ??= { path: candidate, rows };
-    }
-    if (!rows && emptyMatch) {
-      resolvedPath = emptyMatch.path;
-      rows = emptyMatch.rows;
+      emptyMatch ??= { path: candidate, rows: candidateRows };
     }
-    if (!rows) continue;
-    const storedPath = resolvedPath ?? path;
-    const name = storedPath
-      .split('.')
-      .filter(Boolean)
-      .at(-1)
-      ?.replace(/\[\d+\]$/, '');
-    const listName = name || storedPath;
+    resolved ??= emptyMatch;
+    if (!resolved) continue;
     const existing = lists[listName];
-    if (existing?.rows.length && rows.length === 0) {
+    if (existing?.rows.length && resolved.rows.length === 0) {
       continue;
     }
-    lists[listName] = { path: storedPath, rows };
+    lists[listName] = resolved;
   }
   return lists;
 }
@@ -1084,6 +1077,7 @@ export function createToolExecuteResult<TResult = unknown>(input: {
     toolId: input.metadata.toolId,
     execution: input.execution,
     targets,
+    listExtractorPaths: [...(input.metadata.listExtractorPaths ?? [])],
     ...(input.metadata.extractors
       ? { extractors: input.metadata.extractors }
       : {}),
@@ -1208,6 +1202,21 @@ export function attachToolResultListDataset<T extends Record<string, unknown>>(
     count: input.count,
     keys: input.keys ?? existing?.keys ?? {},
   };
+  const declaredPaths = result._metadata.listExtractorPaths ?? [];
+  const inputCandidates = new Set(candidateResultPaths(input.path));
+  const equivalentDeclaration = declaredPaths.find((path) =>
+    candidateResultPaths(path).some((candidate) =>
+      inputCandidates.has(candidate),
+    ),
+  );
+  result._metadata.listExtractorPaths = equivalentDeclaration
+    ? [...declaredPaths]
+    : [
+        ...declaredPaths.filter(
+          (path) => listNameFromDeclaredPath(path) !== input.name,
+        ),
+        input.path,
+      ];
   const accessor = {
     path: input.path,
     count: input.count,
@@ -1585,9 +1594,9 @@ function metadataInputFromToolExecuteResult(
         [info.path],
       ]),
     ),
-    listExtractorPaths: Object.values(value._metadata.lists).map(
-      (list) => list.path,
-    ),
+    listExtractorPaths:
+      value._metadata.listExtractorPaths ??
+      Object.values(value._metadata.lists).map((list) => list.path),
     listIdentityGetters: Object.fromEntries(
       Object.values(value._metadata.lists)
         .flatMap((list) => Object.entries(list.keys))

package/dist/bundling-sources/shared_libs/tool-execution-error.ts

@@ -20,12 +20,30 @@ export const TOOL_EXECUTION_ERROR_SCHEMA_HEADER =
 const MAX_IDENTIFIER_LENGTH = 200;
 const MAX_CODE_LENGTH = 160;
 
+/**
+ * The boundary responsible for a failed tool call.
+ *
+ * Use `provider` to distinguish a provider answer from caller input and
+ * Deepline infrastructure. `unknown` fails closed and must not trigger a
+ * waterfall fallback.
+ *
+ * @sdkReference errors 020
+ */
 export type ToolExecutionErrorOrigin =
   | 'caller'
   | 'provider'
   | 'deepline'
   | 'unknown';
 
+/**
+ * The stable reason family for a failed tool call.
+ *
+ * Branch on this field only after narrowing to `ToolExecutionError`. Catch
+ * `ProviderTransientError` when the policy is simply “try the next read
+ * provider”; it is the safer and shorter waterfall contract.
+ *
+ * @sdkReference errors 030
+ */
 export type ToolExecutionErrorCategory =
   | 'validation'
   | 'authentication'
@@ -38,6 +56,13 @@ export type ToolExecutionErrorCategory =
   | 'internal'
   | 'unknown';
 
+/**
+ * The transport failure observed when `category` is `network`.
+ *
+ * This is `null` for failures that are not network failures.
+ *
+ * @sdkReference errors 040
+ */
 export type ToolExecutionNetworkKind =
   | 'timeout'
   | 'dns'
@@ -46,27 +71,66 @@ export type ToolExecutionNetworkKind =
   | 'unavailable'
   | 'unknown';
 
+/**
+ * The request boundary on which a network failure occurred.
+ *
+ * `deepline_to_provider` is provider-side. Client and runtime scopes are
+ * Deepline transport failures and never qualify as provider fallthrough.
+ *
+ * @sdkReference errors 050
+ */
 export type ToolExecutionNetworkScope =
   | 'client_to_deepline'
   | 'runtime_to_deepline'
   | 'deepline_to_provider';
 
+/**
+ * Portable version-1 `tool_error` payload.
+ *
+ * This allowlisted shape crosses the API, runtime, and SDK boundaries.
+ * `message` remains on the Error object and is deliberately not a policy
+ * field.
+ *
+ * @sdkReference errors 064
+ */
 export type ToolExecutionFailureV1 = {
+  /** Payload version. */
   schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+  /** Public tool id passed to `tools.execute`. */
   toolId: string;
+  /** Provider responsible for the operation, or `null`. */
   provider: string | null;
+  /** Provider operation name, or `null`. */
   operation: string | null;
+  /** Stable machine-readable failure code, or `null`. */
   code: string | null;
+  /** Boundary responsible for the failure. */
   origin: ToolExecutionErrorOrigin;
+  /** Stable reason family. */
   category: ToolExecutionErrorCategory;
+  /** Whether repeating the same semantic call is delivery-safe. */
   retryable: boolean;
+  /** HTTP status when one exists, or `null`. */
   statusCode: number | null;
+  /** Provider or Deepline request id, or `null`. */
   requestId: string | null;
+  /** Suggested same-call retry delay in milliseconds, or `null`. */
   retryAfterMs: number | null;
+  /** Network failure kind, or `null`. */
   networkKind: ToolExecutionNetworkKind | null;
+  /** Network boundary that failed, or `null`. */
   networkScope: ToolExecutionNetworkScope | null;
 };
 
+/**
+ * Constructor input for a structured tool failure.
+ *
+ * Deepline creates these values while decoding the versioned wire payload.
+ * Customer code normally reads `ToolExecutionError` fields instead of
+ * constructing an error.
+ *
+ * @sdkReference errors 065
+ */
 export type ToolExecutionErrorOptions = Omit<
   ToolExecutionFailureV1,
   'schemaVersion'
@@ -78,6 +142,12 @@ export type ToolExecutionErrorOptions = Omit<
   details?: Record<string, unknown>;
 };
 
+/**
+ * Provider-owned failure categories that may fall through to another read
+ * provider.
+ *
+ * @sdkReference errors 060
+ */
 export type ProviderTransientErrorCategory =
   | 'rate_limit'
   | 'network'
@@ -112,16 +182,39 @@ function applyBrand(value: object, brand: symbol): void {
  *
  * The global brand preserves `instanceof DeeplineError` when a bundled play
  * and the runtime load separate physical copies of this module.
+ *
+ * @sdkReference errors 010
  */
 export class DeeplineError extends Error {
+  /** HTTP status when the failure crossed an HTTP boundary. */
+  statusCode?: number;
+  /** Stable machine-readable error code when one exists. */
+  code?: string;
+  /** Local diagnostic context; not a portable error contract. */
+  details?: Record<string, unknown>;
+
+  /**
+   * Construct a Deepline error.
+   *
+   * SDK and runtime code construct these errors. Application and Play code
+   * normally catches the public subclasses instead.
+   *
+   * @param message Human-readable failure summary.
+   * @param statusCode HTTP status when one exists.
+   * @param code Stable machine-readable code when one exists.
+   * @param details Local diagnostic context; never a portable error contract.
+   */
   constructor(
     message: string,
-    public statusCode?: number,
-    public code?: string,
-    public details?: Record<string, unknown>,
+    statusCode?: number,
+    code?: string,
+    details?: Record<string, unknown>,
   ) {
     super(message);
     this.name = 'DeeplineError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
     applyBrand(this, DEEPLINE_ERROR_BRAND);
   }
 
@@ -139,19 +232,46 @@ export class DeeplineError extends Error {
  * `retryable` means Deepline's delivery/idempotency contract says it is safe
  * to repeat the same semantic call. It does not describe durable receipt
  * repairability and does not make arbitrary side-effecting fallbacks safe.
+ *
+ * In a Play, catch `ProviderTransientError` to continue a read waterfall and
+ * let every other `ToolExecutionError` remain loud. In an SDK client, catch
+ * this base class when you need structured diagnostics for every tool failure.
+ *
+ * @sdkReference errors 070
  */
 export class ToolExecutionError extends DeeplineError {
+  /** Public tool id passed to `tools.execute`. */
   readonly toolId: string;
+  /** Provider responsible for the operation, or `null` when unattributed. */
   readonly provider: string | null;
+  /** Provider operation name, or `null` when unavailable. */
   readonly operation: string | null;
+  /** Boundary responsible for the failure. */
   readonly origin: ToolExecutionErrorOrigin;
+  /** Stable reason family for policy and diagnostics. */
   readonly category: ToolExecutionErrorCategory;
+  /**
+   * Whether repeating the same semantic call is delivery-safe.
+   *
+   * This does not mean the error may be ignored. Waterfall fallthrough is
+   * represented by `ProviderTransientError`.
+   */
   readonly retryable: boolean;
+  /** Provider or Deepline request id, or `null` when unavailable. */
   readonly requestId: string | null;
+  /** Suggested same-call retry delay in milliseconds, or `null`. */
   readonly retryAfterMs: number | null;
+  /** Network failure kind, or `null` for non-network failures. */
   readonly networkKind: ToolExecutionNetworkKind | null;
+  /** Network boundary that failed, or `null` for non-network failures. */
   readonly networkScope: ToolExecutionNetworkScope | null;
 
+  /**
+   * Construct a structured tool error.
+   *
+   * Deepline constructs this from the versioned `tool_error` payload.
+   * Application and Play code should catch it rather than create it.
+   */
   constructor(message: string, options: ToolExecutionErrorOptions) {
     super(
       message,
@@ -211,11 +331,20 @@ export function isProviderTransientFailure(input: {
  * A provider-owned transient failure that is safe to handle as an empty
  * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
  * never satisfy this type.
+ *
+ * `retryable` remains independent: it says whether the same semantic call may
+ * be repeated safely. Falling through to a different read provider depends on
+ * this class, not on `retryable`.
+ *
+ * @sdkReference errors 080
  */
 export class ProviderTransientError extends ToolExecutionError {
+  /** Provider attribution is guaranteed for this subtype. */
   override readonly origin = 'provider' as const;
+  /** Provider failure category that made this error eligible for fallthrough. */
   declare readonly category: ProviderTransientErrorCategory;
 
+  /** Constructed by Deepline when a provider-owned transient failure arrives. */
   constructor(
     message: string,
     options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {