deepline 0.1.109 → 0.1.111

package/dist/repo/apps/play-runner-workers/src/workflow-instance-create.ts

@@ -0,0 +1,44 @@
+export type WorkflowInstanceLike = {
+  id: string;
+};
+
+export type WorkflowInstanceCreateResult<T extends WorkflowInstanceLike> = {
+  instance: T;
+  startMode: 'created' | 'reattached_existing';
+};
+
+export function isWorkflowInstanceAlreadyExistsError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /instance[._ -]?already[._ -]?exists|Instance already exists/i.test(
+    message,
+  );
+}
+
+export async function createOrAttachWorkflowInstance<
+  T extends WorkflowInstanceLike,
+>(input: {
+  create: () => Promise<T>;
+  getExisting: () => Promise<T>;
+}): Promise<WorkflowInstanceCreateResult<T>> {
+  try {
+    return { instance: await input.create(), startMode: 'created' };
+  } catch (error) {
+    if (!isWorkflowInstanceAlreadyExistsError(error)) {
+      throw error;
+    }
+    try {
+      return {
+        instance: await input.getExisting(),
+        startMode: 'reattached_existing',
+      };
+    } catch (attachError) {
+      const message =
+        attachError instanceof Error
+          ? attachError.message
+          : String(attachError);
+      throw new Error(
+        `Workflow instance already exists but could not be reattached: ${message}`,
+      );
+    }
+  }
+}

package/dist/repo/apps/play-runner-workers/src/workflow-retry.ts

@@ -1,7 +1,4 @@
-import {
-  isCloudflareDurableObjectCodeUpdatedError,
-  normalizePlayRunFailure,
-} from '../../../shared_libs/play-runtime/run-failure';
+import { normalizePlayRunFailure } from '../../../shared_libs/play-runtime/run-failure';
 
 export const PLATFORM_DEPLOY_WORKFLOW_RETRY_LIMIT = 1;
 
@@ -26,25 +23,24 @@ export function decideWorkflowPlatformRetry(input: {
   if (!input.error) {
     return { action: 'fail', reason: null, message: null };
   }
-  const retryablePlatformReset = isCloudflareDurableObjectCodeUpdatedError(
-    input.error,
-  );
+  const failure = normalizePlayRunFailure(input.error);
+  const retryablePlatformReset = failure.code === 'PLATFORM_DEPLOY_INTERRUPTED';
   if (
     retryablePlatformReset &&
     input.retryAttempts < PLATFORM_DEPLOY_WORKFLOW_RETRY_LIMIT
   ) {
     return {
       action: 'retry',
-      reason: 'cloudflare_durable_object_code_updated',
+      reason: 'cloudflare_durable_object_reset',
       nextAttempt: input.retryAttempts + 1,
-      message: normalizePlayRunFailure(input.error).message,
+      message: failure.message,
     };
   }
   return {
     action: 'fail',
     reason: retryablePlatformReset
-      ? 'cloudflare_durable_object_code_updated_retry_exhausted'
+      ? 'cloudflare_durable_object_reset_retry_exhausted'
       : null,
-    message: normalizePlayRunFailure(input.error).message,
+    message: failure.message,
   };
 }

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

@@ -413,11 +413,14 @@ export type BillingPlanEntry = {
 };
 
 /** One usage metric published in the billing catalog. */
-export type BillingMetricEntry = {
+export type BillingMeterEntry = {
   id: string;
   name: string;
 };
 
+/** @deprecated Use BillingMeterEntry. Retained for wire/API alias compatibility. */
+export type BillingMetricEntry = BillingMeterEntry;
+
 /** The caller's active plan as reported by the plans endpoint. */
 export type BillingActivePlan = {
   plan_family_id: string;
@@ -440,6 +443,8 @@ export type BillingPlansResult = {
   catalog_version: string;
   active_plan: BillingActivePlan;
   plans: BillingPlanEntry[];
+  meters: BillingMeterEntry[];
+  /** @deprecated Use meters. Retained for installed SDK compatibility. */
   metrics: BillingMetricEntry[];
 };
 
@@ -1075,12 +1080,12 @@ export 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);
    * ```
@@ -1120,6 +1125,7 @@ export class DeeplineClient {
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
       { payload: input },
       headers,
+      { forbiddenAsApiError: true },
     );
   }
 
@@ -1228,7 +1234,7 @@ export class DeeplineClient {
           ? { 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 } : {}),
       },
@@ -1338,10 +1344,15 @@ export class DeeplineClient {
         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,
+      },
+      undefined,
+      { forbiddenAsApiError: true, retryApiErrors: true },
+    );
   }
 
   /**
@@ -1379,7 +1390,12 @@ export class DeeplineClient {
     }>;
   }> {
     if (artifacts.length === 0) {
-      return this.http.post('/api/v2/plays/artifacts', { artifacts });
+      return this.http.post(
+        '/api/v2/plays/artifacts',
+        { artifacts },
+        undefined,
+        { forbiddenAsApiError: true, retryApiErrors: true },
+      );
     }
     const compiledArtifacts = await mapWithConcurrency(
       artifacts,
@@ -1414,9 +1430,14 @@ export class DeeplineClient {
             triggerMetadata?: unknown;
             triggerBindings?: unknown;
           }>;
-        }>('/api/v2/plays/artifacts', {
-          artifacts: chunk,
-        }),
+        }>(
+          '/api/v2/plays/artifacts',
+          {
+            artifacts: chunk,
+          },
+          undefined,
+          { forbiddenAsApiError: true, retryApiErrors: true },
+        ),
       );
     }
     return {
@@ -2446,6 +2467,8 @@ export class DeeplineClient {
     return this.http.post<PublishPlayVersionResult>(
       `/api/v2/plays/${encodedName}/live`,
       request,
+      undefined,
+      { forbiddenAsApiError: true },
     );
   }
 

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

@@ -10,7 +10,7 @@
  *
  * 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');
@@ -77,7 +77,7 @@ export 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`);

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

@@ -35,6 +35,8 @@ import {
 } from '../../shared_libs/play-runtime/coordinator-headers.js';
 
 const MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
+const 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.';
 
 interface RequestOptions {
   method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -51,6 +53,11 @@ interface RequestOptions {
    * {@link AuthError}.
    */
   forbiddenAsApiError?: boolean;
+  /**
+   * Retry HTTP 408/425/5xx JSON API responses. Use only for idempotent requests;
+   * most mutating API calls must fail loudly after the first server response.
+   */
+  retryApiErrors?: boolean;
 }
 
 interface StreamOptions {
@@ -114,6 +121,7 @@ export class HttpClient {
       '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,
@@ -270,6 +278,9 @@ export class HttpClient {
           }
 
           if (!response.ok) {
+            const retryableApiError =
+              options?.retryApiErrors === true &&
+              isRetryableApiErrorResponse(response.status);
             // A 5xx that escaped a Worker can return Cloudflare's default HTML
             // error page. Never surface raw HTML to CLI users: replace the
             // message with a structured summary and store a short flag in
@@ -280,7 +291,7 @@ export class HttpClient {
               response.headers.get('content-type'),
             );
             if (htmlError) {
-              throw new DeeplineError(
+              lastError = new DeeplineError(
                 htmlError.message(response.status),
                 response.status,
                 'API_ERROR',
@@ -292,6 +303,11 @@ export class HttpClient {
                     : {}),
                 },
               );
+              if (retryableApiError && attempt < this.config.maxRetries) {
+                retryAfterDelayMs = parseOptionalRetryAfter(response);
+                break;
+              }
+              throw lastError;
             }
             const errorValue =
               typeof parsed === 'object' && parsed && 'error' in parsed
@@ -313,9 +329,20 @@ export class HttpClient {
                         'string'
                     ? (parsed as Record<string, string>).message
                     : `HTTP ${response.status}`;
-            throw new DeeplineError(msg, response.status, 'API_ERROR', {
+            const apiErrorCode =
+              errorValue &&
+              typeof errorValue === 'object' &&
+              typeof (errorValue as Record<string, unknown>).code === 'string'
+                ? (errorValue as Record<string, string>).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 as T;
@@ -341,7 +368,7 @@ export class HttpClient {
     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));
   }
 
   /**
@@ -427,9 +454,11 @@ export class HttpClient {
     }
 
     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}.`,
+      ),
     );
   }
 
@@ -444,11 +473,16 @@ export class HttpClient {
     path: string,
     body: unknown,
     headers?: Record<string, string>,
+    options?: Pick<
+      RequestOptions,
+      'forbiddenAsApiError' | 'retryApiErrors' | 'timeout'
+    >,
   ): Promise<T> {
     return this.request<T>(path, {
       method: 'POST',
       body,
       headers,
+      ...options,
     });
   }
 
@@ -502,6 +536,10 @@ function parseResponseBody(body: string): unknown {
   }
 }
 
+function isRetryableApiErrorResponse(status: number): boolean {
+  return status === 408 || status === 425 || (status >= 500 && status < 600);
+}
+
 /**
  * Detect a raw Cloudflare HTML error page in an error response body.
  *
@@ -579,6 +617,10 @@ function apiErrorMessage(parsed: unknown, status: number): string {
 
 /** Parse the `Retry-After` header as milliseconds. Falls back to 5000ms. */
 function parseRetryAfter(response: Response): number {
+  return parseOptionalRetryAfter(response) ?? 5000;
+}
+
+function parseOptionalRetryAfter(response: Response): number | null {
   const header = response.headers.get('retry-after');
   if (header) {
     const seconds = Number(header);
@@ -586,7 +628,7 @@ function parseRetryAfter(response: Response): number {
       return seconds * 1000;
     }
   }
-  return 5000;
+  return null;
 }
 
 /**
@@ -670,3 +712,41 @@ function decodeSseFrame<TEvent extends LiveEventEnvelope>(
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+function isTruthyEnv(name: string): boolean {
+  const normalized = process.env[name]?.trim().toLowerCase();
+  return ['1', 'true', 'yes', 'on'].includes(normalized ?? '');
+}
+
+function isCoworkLikeSandbox(): boolean {
+  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(): string {
+  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: string): string {
+  if (!isCoworkLikeSandbox() || message.includes(COWORK_NETWORK_HINT)) {
+    return message;
+  }
+  return `${message}\n${COWORK_NETWORK_HINT}`;
+}

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

@@ -1456,7 +1456,7 @@ export 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;
    * ```

package/dist/repo/sdk/src/plays/bundle-play-file.ts

@@ -141,6 +141,9 @@ export function createSdkPlayBundlingAdapter(): PlayBundlingAdapter {
     sdkWorkersEntryFile: SDK_WORKERS_ENTRY_FILE,
     workersHarnessEntryFile: WORKERS_HARNESS_ENTRY_FILE,
     workersHarnessFilesDir: WORKERS_HARNESS_FILES_DIR,
+    workersRuntimeFingerprintDirs: [
+      resolve(PROJECT_ROOT, 'shared_libs', 'play-runtime'),
+    ],
     discoverPackagedLocalFiles,
     warnAboutNonDevelopmentBundling,
   };
@@ -155,7 +158,8 @@ export async function bundlePlayFile(
     exportName: options.exportName,
     adapter: createSdkPlayBundlingAdapter(),
   });
-  if (result.success) validatePlaySourceFilesHaveNoInlineSecrets(result.sourceFiles);
+  if (result.success)
+    validatePlaySourceFilesHaveNoInlineSecrets(result.sourceFiles);
   return result;
 }
 

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

@@ -4,9 +4,11 @@
  * Ordinary SDK PRs do NOT bump `version` here. Patch version selection
  * happens at publish time: on push to main, `.github/workflows/sdk-release.yml`
  * (via `scripts/sdk-release-autobump.ts`) compares the built package against
- * the published npm tarball and, when the content changed, stamps the next
- * unpublished patch into `version` + `supportPolicy.latest` and publishes it
- * in the same run.
+ * the latest published npm tarball and, when the content changed, stamps the
+ * next unpublished patch into `version` + `supportPolicy.latest` in the CI
+ * workspace only and publishes it in the same run. That patch stamp is not
+ * committed back to main; production endpoints read npm metadata when they
+ * need the newest patch-level SDK/CLI version.
  *
  * Edit THIS file by hand only for deliberate release decisions:
  *   - minor/major version bumps (set `version` and `supportPolicy.latest`),
@@ -23,17 +25,18 @@
  *     `scripts/sync-sdk-package-version.ts`, which runs as part of
  *     `bun run sdk:build`.
  *   - `contracts/sdk-api.manifest.json` is regenerated at build time from
- *     `src/lib/sdk/api-routes.ts` and the apiContract here; the hash in
- *     `contracts/sdk-api.manifest.hash` is the invariant that lands in git.
+ *     `src/lib/sdk/api-routes.ts` and the apiContract here; the matching
+ *     `contracts/sdk-api.manifest.hash` is an ignored local/CI audit artifact.
  *
- * Any drift between this file and the derived locations is a
- * `check:sdk-release-readiness` failure with a one-shot fix command.
+ * Any drift between release source and derived release locations is a
+ * `check:sdk-release-readiness` failure with a one-shot fix command; SDK/API
+ * compatibility policy is enforced by `bun run sdk:api-contract:check`.
  */
 
 export type SdkReleaseChannel = 'latest' | 'next' | 'beta';
 
 export type SdkSupportPolicy = {
-  /** Newest published deepline SDK/CLI on npm. */
+  /** Checked-in latest policy value; publish-time patch latest is read from npm. */
   latest: string;
   /**
    * Anything strictly below this returns `status: "unsupported"` from
@@ -96,10 +99,10 @@ export const 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: [

package/dist/repo/sdk/src/tool-output.ts

@@ -203,8 +203,8 @@ function findBestArrayCandidate(
  *
  * @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/repo/sdk/src/types.ts

@@ -138,9 +138,9 @@ export type {
  * schema, examples, pricing, and extraction guidance before executing.
  */
 export 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;
@@ -154,6 +154,8 @@ export 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`. */
@@ -313,8 +315,8 @@ export 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: {...} }
  * ```
@@ -933,8 +935,9 @@ export 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;
 }