deepline 0.1.109 → 0.1.111

package/dist/index.d.mts

@@ -353,9 +353,9 @@ interface ToolPricingSummary {
  * schema, examples, pricing, and extraction guidance before executing.
  */
 interface ToolDefinition {
-    /** Unique tool identifier used in API calls (e.g. `"apollo_people_search"`). */
+    /** Unique tool identifier used in API calls (e.g. `"dropleads_search_people"`). */
     toolId: string;
-    /** Provider that backs this tool (e.g. `"apollo"`, `"hunter"`, `"test"`). */
+    /** Provider that backs this tool (e.g. `"hunter"`, `"dropleads"`, `"test"`). */
     provider: string;
     /** Human-readable name for display. */
     displayName: string;
@@ -369,6 +369,8 @@ interface ToolDefinition {
     operationId?: string;
     /** Alternative names that resolve to this tool. */
     operationAliases?: string[];
+    /** Explicit globally runnable play reference for play-backed catalog entries. */
+    playReference?: `prebuilt/${string}`;
     /** Whether detailed input schema is available from `tools describe`. */
     hasInputSchema?: boolean;
     /** Whether detailed output schema is available from `tools describe`. */
@@ -515,8 +517,8 @@ interface ToolSearchResult {
  *
  * @example
  * ```typescript
- * const meta = await client.getTool('apollo_people_search');
- * console.log(meta.displayName);              // "Apollo People Search"
+ * const meta = await client.getTool('dropleads_search_people');
+ * console.log(meta.displayName);              // "DropLeads People Search"
  * console.log(meta.estimatedCreditsRange);     // "1-5"
  * console.log(meta.samples);                   // { input: {...}, output: {...} }
  * ```
@@ -1101,8 +1103,9 @@ interface StartPlayRunRequest {
     /** Optionally let the start request wait briefly and return a terminal result. */
     waitForCompletionMs?: number;
     /**
-     * Per-run execution profile override. The server defaults to `workers_edge`;
-     * tests can pass `local` here. Most callers should leave this unset.
+     * Per-run execution profile override. The server defaults to workers_edge;
+     * tests and runtime probes can pass a different profile here. Most callers
+     * should leave this unset.
      */
     profile?: string;
 }
@@ -1462,10 +1465,12 @@ type BillingPlanEntry = {
     acquirable: boolean;
 };
 /** One usage metric published in the billing catalog. */
-type BillingMetricEntry = {
+type BillingMeterEntry = {
     id: string;
     name: string;
 };
+/** @deprecated Use BillingMeterEntry. Retained for wire/API alias compatibility. */
+type BillingMetricEntry = BillingMeterEntry;
 /** The caller's active plan as reported by the plans endpoint. */
 type BillingActivePlan = {
     plan_family_id: string;
@@ -1487,6 +1492,8 @@ type BillingPlansResult = {
     catalog_version: string;
     active_plan: BillingActivePlan;
     plans: BillingPlanEntry[];
+    meters: BillingMeterEntry[];
+    /** @deprecated Use meters. Retained for installed SDK compatibility. */
     metrics: BillingMetricEntry[];
 };
 /**
@@ -1610,12 +1617,12 @@ declare class DeeplineClient {
      * Returns everything from {@link ToolDefinition} plus pricing info, sample
      * inputs/outputs, failure modes, and cost estimates.
      *
-     * @param toolId - Tool identifier (e.g. `"apollo_people_search"`)
+     * @param toolId - Tool identifier (e.g. `"dropleads_search_people"`)
      * @returns Full tool metadata
      *
      * @example
      * ```typescript
-     * const meta = await client.getTool('apollo_people_search');
+     * const meta = await client.getTool('dropleads_search_people');
      * console.log(`Cost: ${meta.estimatedCreditsRange} credits`);
      * console.log(`Input schema:`, meta.inputSchema);
      * ```
@@ -2362,7 +2369,7 @@ declare const SDK_API_CONTRACT: string;
  *
  * const client = new DeeplineClient();
  * try {
- *   await client.executeTool('apollo_people_search', { query: 'cto' });
+ *   await client.executeTool('dropleads_search_people', { query: 'cto' });
  * } catch (err) {
  *   if (err instanceof AuthError) {
  *     console.error('Bad API key — run: deepline auth register');
@@ -2425,7 +2432,7 @@ declare class AuthError extends DeeplineError {
  * import { RateLimitError } from 'deepline';
  *
  * try {
- *   await client.executeTool('apollo_people_search', { query: 'cto' });
+ *   await client.executeTool('dropleads_search_people', { query: 'cto' });
  * } catch (err) {
  *   if (err instanceof RateLimitError) {
  *     console.log(`Retry after ${err.retryAfterMs}ms`);
@@ -3819,7 +3826,7 @@ declare class DeeplineContext {
      * @example
      * ```typescript
      * const tools = await deepline.tools.list();
-     * const meta = await deepline.tools.get('apollo_people_search');
+     * const meta = await deepline.tools.get('dropleads_search_people');
      * const companyLookup = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
      * const company = companyLookup.toolResponse.raw;
      * ```
@@ -4080,8 +4087,8 @@ type Scalar = string | number | boolean | null;
  *
  * @example Using configured paths (from tool metadata)
  * ```typescript
- * const meta = await client.getTool('apollo_people_search');
- * const result = await client.executeTool('apollo_people_search', { query: 'cto' });
+ * const meta = await client.getTool('dropleads_search_people');
+ * const result = await client.executeTool('dropleads_search_people', { query: 'cto' });
  *
  * const list = tryConvertToList(result, {
  *   listExtractorPaths: meta.listExtractorPaths,

package/dist/index.d.ts

@@ -353,9 +353,9 @@ interface ToolPricingSummary {
  * schema, examples, pricing, and extraction guidance before executing.
  */
 interface ToolDefinition {
-    /** Unique tool identifier used in API calls (e.g. `"apollo_people_search"`). */
+    /** Unique tool identifier used in API calls (e.g. `"dropleads_search_people"`). */
     toolId: string;
-    /** Provider that backs this tool (e.g. `"apollo"`, `"hunter"`, `"test"`). */
+    /** Provider that backs this tool (e.g. `"hunter"`, `"dropleads"`, `"test"`). */
     provider: string;
     /** Human-readable name for display. */
     displayName: string;
@@ -369,6 +369,8 @@ interface ToolDefinition {
     operationId?: string;
     /** Alternative names that resolve to this tool. */
     operationAliases?: string[];
+    /** Explicit globally runnable play reference for play-backed catalog entries. */
+    playReference?: `prebuilt/${string}`;
     /** Whether detailed input schema is available from `tools describe`. */
     hasInputSchema?: boolean;
     /** Whether detailed output schema is available from `tools describe`. */
@@ -515,8 +517,8 @@ interface ToolSearchResult {
  *
  * @example
  * ```typescript
- * const meta = await client.getTool('apollo_people_search');
- * console.log(meta.displayName);              // "Apollo People Search"
+ * const meta = await client.getTool('dropleads_search_people');
+ * console.log(meta.displayName);              // "DropLeads People Search"
  * console.log(meta.estimatedCreditsRange);     // "1-5"
  * console.log(meta.samples);                   // { input: {...}, output: {...} }
  * ```
@@ -1101,8 +1103,9 @@ interface StartPlayRunRequest {
     /** Optionally let the start request wait briefly and return a terminal result. */
     waitForCompletionMs?: number;
     /**
-     * Per-run execution profile override. The server defaults to `workers_edge`;
-     * tests can pass `local` here. Most callers should leave this unset.
+     * Per-run execution profile override. The server defaults to workers_edge;
+     * tests and runtime probes can pass a different profile here. Most callers
+     * should leave this unset.
      */
     profile?: string;
 }
@@ -1462,10 +1465,12 @@ type BillingPlanEntry = {
     acquirable: boolean;
 };
 /** One usage metric published in the billing catalog. */
-type BillingMetricEntry = {
+type BillingMeterEntry = {
     id: string;
     name: string;
 };
+/** @deprecated Use BillingMeterEntry. Retained for wire/API alias compatibility. */
+type BillingMetricEntry = BillingMeterEntry;
 /** The caller's active plan as reported by the plans endpoint. */
 type BillingActivePlan = {
     plan_family_id: string;
@@ -1487,6 +1492,8 @@ type BillingPlansResult = {
     catalog_version: string;
     active_plan: BillingActivePlan;
     plans: BillingPlanEntry[];
+    meters: BillingMeterEntry[];
+    /** @deprecated Use meters. Retained for installed SDK compatibility. */
     metrics: BillingMetricEntry[];
 };
 /**
@@ -1610,12 +1617,12 @@ declare class DeeplineClient {
      * Returns everything from {@link ToolDefinition} plus pricing info, sample
      * inputs/outputs, failure modes, and cost estimates.
      *
-     * @param toolId - Tool identifier (e.g. `"apollo_people_search"`)
+     * @param toolId - Tool identifier (e.g. `"dropleads_search_people"`)
      * @returns Full tool metadata
      *
      * @example
      * ```typescript
-     * const meta = await client.getTool('apollo_people_search');
+     * const meta = await client.getTool('dropleads_search_people');
      * console.log(`Cost: ${meta.estimatedCreditsRange} credits`);
      * console.log(`Input schema:`, meta.inputSchema);
      * ```
@@ -2362,7 +2369,7 @@ declare const SDK_API_CONTRACT: string;
  *
  * const client = new DeeplineClient();
  * try {
- *   await client.executeTool('apollo_people_search', { query: 'cto' });
+ *   await client.executeTool('dropleads_search_people', { query: 'cto' });
  * } catch (err) {
  *   if (err instanceof AuthError) {
  *     console.error('Bad API key — run: deepline auth register');
@@ -2425,7 +2432,7 @@ declare class AuthError extends DeeplineError {
  * import { RateLimitError } from 'deepline';
  *
  * try {
- *   await client.executeTool('apollo_people_search', { query: 'cto' });
+ *   await client.executeTool('dropleads_search_people', { query: 'cto' });
  * } catch (err) {
  *   if (err instanceof RateLimitError) {
  *     console.log(`Retry after ${err.retryAfterMs}ms`);
@@ -3819,7 +3826,7 @@ declare class DeeplineContext {
      * @example
      * ```typescript
      * const tools = await deepline.tools.list();
-     * const meta = await deepline.tools.get('apollo_people_search');
+     * const meta = await deepline.tools.get('dropleads_search_people');
      * const companyLookup = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
      * const company = companyLookup.toolResponse.raw;
      * ```
@@ -4080,8 +4087,8 @@ type Scalar = string | number | boolean | null;
  *
  * @example Using configured paths (from tool metadata)
  * ```typescript
- * const meta = await client.getTool('apollo_people_search');
- * const result = await client.executeTool('apollo_people_search', { query: 'cto' });
+ * const meta = await client.getTool('dropleads_search_people');
+ * const result = await client.executeTool('dropleads_search_people', { query: 'cto' });
  *
  * const list = tryConvertToList(result, {
  *   listExtractorPaths: meta.listExtractorPaths,

package/dist/index.js

@@ -274,10 +274,10 @@ var SDK_RELEASE = {
   // skill on the sdk sync surface, and the people-search-to-email prebuilt.
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
-  version: "0.1.109",
+  version: "0.1.111",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.109",
+    latest: "0.1.111",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -304,6 +304,7 @@ var SYNTHETIC_RUN_HEADER = "x-deepline-synthetic-run";
 
 // src/http.ts
 var MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
+var COWORK_NETWORK_HINT = "Claude Cowork appears to be running Deepline in a network-restricted sandbox. In Claude Desktop, open Settings > Capabilities, turn on Allow network egress, and set Domain allowlist to All domains for the Cowork session.";
 var HttpClient = class {
   constructor(config) {
     this.config = config;
@@ -339,6 +340,7 @@ var HttpClient = class {
       "User-Agent": `deepline-ts-sdk/${SDK_VERSION}`,
       "X-Deepline-Client-Family": "sdk",
       "X-Deepline-CLI-Family": "sdk",
+      "X-Deepline-Agent-Runtime": detectAgentRuntime(),
       "X-Deepline-CLI-Version": SDK_VERSION,
       "X-Deepline-SDK-Version": SDK_VERSION,
       "X-Deepline-API-Contract": SDK_API_CONTRACT,
@@ -441,12 +443,13 @@ var HttpClient = class {
             parsed = body;
           }
           if (!response.ok) {
+            const retryableApiError = options?.retryApiErrors === true && isRetryableApiErrorResponse(response.status);
             const htmlError = detectHtmlErrorBody(
               body,
               response.headers.get("content-type")
             );
             if (htmlError) {
-              throw new DeeplineError(
+              lastError = new DeeplineError(
                 htmlError.message(response.status),
                 response.status,
                 "API_ERROR",
@@ -456,12 +459,23 @@ var HttpClient = class {
                   ...htmlError.workerThrewException ? { workerThrewException: true } : {}
                 }
               );
+              if (retryableApiError && attempt < this.config.maxRetries) {
+                retryAfterDelayMs = parseOptionalRetryAfter(response);
+                break;
+              }
+              throw lastError;
             }
             const errorValue = typeof parsed === "object" && parsed && "error" in parsed ? parsed.error : void 0;
             const msg = typeof errorValue === "string" ? errorValue : errorValue && typeof errorValue === "object" && "message" in errorValue && typeof errorValue.message === "string" ? errorValue.message : typeof parsed === "object" && parsed && "message" in parsed && typeof parsed.message === "string" ? parsed.message : `HTTP ${response.status}`;
-            throw new DeeplineError(msg, response.status, "API_ERROR", {
+            const apiErrorCode = errorValue && typeof errorValue === "object" && typeof errorValue.code === "string" ? errorValue.code : "API_ERROR";
+            lastError = new DeeplineError(msg, response.status, apiErrorCode, {
               response: parsed
             });
+            if (retryableApiError && attempt < this.config.maxRetries) {
+              retryAfterDelayMs = parseOptionalRetryAfter(response);
+              break;
+            }
+            throw lastError;
           }
           return parsed;
         } catch (error) {
@@ -482,7 +496,7 @@ var HttpClient = class {
       throw lastError;
     }
     const errorMessage = lastError?.message ? `Unable to connect to ${baseUrl}. ${lastError.message}` : `Unable to connect to ${baseUrl}. Is the computer able to access the url?`;
-    throw new DeeplineError(errorMessage);
+    throw new DeeplineError(withCoworkNetworkHint(errorMessage));
   }
   /**
    * Send a GET request.
@@ -554,7 +568,9 @@ var HttpClient = class {
       }
     }
     throw new DeeplineError(
-      lastError?.message ? `Unable to stream from ${this.config.baseUrl}. ${lastError.message}` : `Unable to stream from ${this.config.baseUrl}.`
+      withCoworkNetworkHint(
+        lastError?.message ? `Unable to stream from ${this.config.baseUrl}. ${lastError.message}` : `Unable to stream from ${this.config.baseUrl}.`
+      )
     );
   }
   /**
@@ -564,11 +580,12 @@ var HttpClient = class {
    * @param path - API path
    * @param body - Request body (will be JSON-serialized)
    */
-  async post(path, body, headers) {
+  async post(path, body, headers, options) {
     return this.request(path, {
       method: "POST",
       body,
-      headers
+      headers,
+      ...options
     });
   }
   async postFormData(path, formData, headers) {
@@ -609,6 +626,9 @@ function parseResponseBody(body) {
     return body;
   }
 }
+function isRetryableApiErrorResponse(status) {
+  return status === 408 || status === 425 || status >= 500 && status < 600;
+}
 function detectHtmlErrorBody(body, contentType) {
   const trimmed = body.trim();
   const lower = trimmed.toLowerCase();
@@ -648,6 +668,9 @@ function apiErrorMessage(parsed, status) {
   return `HTTP ${status}`;
 }
 function parseRetryAfter(response) {
+  return parseOptionalRetryAfter(response) ?? 5e3;
+}
+function parseOptionalRetryAfter(response) {
   const header = response.headers.get("retry-after");
   if (header) {
     const seconds = Number(header);
@@ -655,7 +678,7 @@ function parseRetryAfter(response) {
       return seconds * 1e3;
     }
   }
-  return 5e3;
+  return null;
 }
 function buildCandidateUrls(url) {
   try {
@@ -712,6 +735,39 @@ function decodeSseFrame(frame) {
 function sleep(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
+function isTruthyEnv(name) {
+  const normalized = process.env[name]?.trim().toLowerCase();
+  return ["1", "true", "yes", "on"].includes(normalized ?? "");
+}
+function isCoworkLikeSandbox() {
+  const pluginMode = isTruthyEnv("DEEPLINE_PLUGIN_MODE");
+  const claudeRemote = isTruthyEnv("CLAUDE_CODE_REMOTE");
+  const projectDir = Boolean(process.env.CLAUDE_PROJECT_DIR?.trim());
+  const pluginRoot = Boolean(process.env.DEEPLINE_PLUGIN_ROOT?.trim());
+  const home = process.env.HOME?.trim() ?? "";
+  const sessionHome = home.startsWith("/sessions/");
+  return (pluginMode || pluginRoot) && (claudeRemote || projectDir || sessionHome);
+}
+function detectAgentRuntime() {
+  if (process.env.CODEX_THREAD_ID?.trim()) return "codex";
+  if (isCoworkLikeSandbox()) return "claude_cowork";
+  if (process.env.CLAUDECODE?.trim() === "1") return "claude_code";
+  if (process.env.CLINE_ACTIVE?.trim().toLowerCase() === "true") return "cline";
+  if (process.env.CURSOR_TRACE_ID?.trim() || process.env.CURSOR_AGENT?.trim()) {
+    return "cursor";
+  }
+  if (process.env.WINDSURF?.trim() || process.env.CASCADE?.trim()) {
+    return "windsurf";
+  }
+  return "unknown";
+}
+function withCoworkNetworkHint(message) {
+  if (!isCoworkLikeSandbox() || message.includes(COWORK_NETWORK_HINT)) {
+    return message;
+  }
+  return `${message}
+${COWORK_NETWORK_HINT}`;
+}
 
 // src/stream-reconnect.ts
 var STREAM_RECONNECT_BASE_DELAY_MS = 500;
@@ -1988,12 +2044,12 @@ var DeeplineClient = class {
    * Returns everything from {@link ToolDefinition} plus pricing info, sample
    * inputs/outputs, failure modes, and cost estimates.
    *
-   * @param toolId - Tool identifier (e.g. `"apollo_people_search"`)
+   * @param toolId - Tool identifier (e.g. `"dropleads_search_people"`)
    * @returns Full tool metadata
    *
    * @example
    * ```typescript
-   * const meta = await client.getTool('apollo_people_search');
+   * const meta = await client.getTool('dropleads_search_people');
    * console.log(`Cost: ${meta.estimatedCreditsRange} credits`);
    * console.log(`Input schema:`, meta.inputSchema);
    * ```
@@ -2025,7 +2081,8 @@ var DeeplineClient = class {
     return this.http.post(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
       { payload: input },
-      headers
+      headers,
+      { forbiddenAsApiError: true }
     );
   }
   /**
@@ -2107,7 +2164,7 @@ var DeeplineClient = class {
         ...request.force ? { force: true } : {},
         ...typeof request.waitForCompletionMs === "number" ? { waitForCompletionMs: request.waitForCompletionMs } : {},
         // Profile selection is the API's job, not the CLI's. The server
-        // hardcodes workers_edge as the default; tests that want a
+        // defaults to workers_edge; tests and runtime probes that want a
         // different profile pass `request.profile` explicitly.
         ...request.profile ? { profile: request.profile } : {}
       }
@@ -2172,10 +2229,15 @@ var DeeplineClient = class {
       sourceFiles: input.sourceFiles,
       artifact: input.artifact
     });
-    return this.http.post("/api/v2/plays/artifacts", {
-      ...input,
-      compilerManifest
-    });
+    return this.http.post(
+      "/api/v2/plays/artifacts",
+      {
+        ...input,
+        compilerManifest
+      },
+      void 0,
+      { forbiddenAsApiError: true, retryApiErrors: true }
+    );
   }
   /**
    * Register multiple bundled play artifacts in one request.
@@ -2185,7 +2247,12 @@ var DeeplineClient = class {
    */
   async registerPlayArtifacts(artifacts) {
     if (artifacts.length === 0) {
-      return this.http.post("/api/v2/plays/artifacts", { artifacts });
+      return this.http.post(
+        "/api/v2/plays/artifacts",
+        { artifacts },
+        void 0,
+        { forbiddenAsApiError: true, retryApiErrors: true }
+      );
     }
     const compiledArtifacts = await mapWithConcurrency(
       artifacts,
@@ -2203,9 +2270,14 @@ var DeeplineClient = class {
     const responses = [];
     for (const chunk of chunkRegisterPlayArtifacts(compiledArtifacts)) {
       responses.push(
-        await this.http.post("/api/v2/plays/artifacts", {
-          artifacts: chunk
-        })
+        await this.http.post(
+          "/api/v2/plays/artifacts",
+          {
+            artifacts: chunk
+          },
+          void 0,
+          { forbiddenAsApiError: true, retryApiErrors: true }
+        )
       );
     }
     return {
@@ -3010,7 +3082,9 @@ var DeeplineClient = class {
     const encodedName = encodeURIComponent(name);
     return this.http.post(
       `/api/v2/plays/${encodedName}/live`,
-      request
+      request,
+      void 0,
+      { forbiddenAsApiError: true }
     );
   }
   /**
@@ -4252,7 +4326,7 @@ var DeeplineContext = class {
    * @example
    * ```typescript
    * const tools = await deepline.tools.list();
-   * const meta = await deepline.tools.get('apollo_people_search');
+   * const meta = await deepline.tools.get('dropleads_search_people');
    * const companyLookup = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
    * const company = companyLookup.toolResponse.raw;
    * ```