deepline 0.3.148 → 0.3.150

package/dist/index.mjs

@@ -768,7 +768,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.148",
+  version: "0.3.150",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -1509,6 +1509,11 @@ var HttpClient = class {
             body: options?.formData !== void 0 ? typeof options.formData === "function" ? options.formData() : options.formData : options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
             signal: controller.signal
           });
+          options?.onResponse?.(response);
+          if (response.status === 404 && options?.allowNotFound) {
+            clearTimeout(timeoutId);
+            return null;
+          }
           clearTimeout(timeoutId);
           const body = await response.text();
           const parsed = parseResponseBody(body);
@@ -1648,7 +1653,8 @@ var HttpClient = class {
             retryAfterMs: null,
             networkKind: code === "NETWORK_TIMEOUT" ? "timeout" : code === "NETWORK_ABORTED" ? "unknown" : "unavailable",
             networkScope: "client_to_deepline",
-            details: mappedNetworkError.details
+            details: mappedNetworkError.details,
+            publicDetails: options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : null
           }
         ),
         lastError
@@ -4127,6 +4133,56 @@ var MONITOR_NON_RETRYABLE_MUTATION_OPTIONS = {
   exactUrlOnly: true
 };
 var RAW_V2_EXECUTE_RESPONSE_CONTRACT = RAW_V2_TOOL_RESPONSE_CONTRACT;
+var DEFAULT_EXECUTION_RECOVERY_TIMEOUT_MS = 15 * 60 * 1e3;
+function validateExecutionIdempotencyKey(key) {
+  if (typeof key !== "string" || key.length < 1 || key.length > 200 || !/^[A-Za-z0-9._:-]+$/.test(key)) {
+    throw new DeeplineError(
+      "Execution idempotency keys must be 1\u2013200 ASCII letters, digits, dots, underscores, colons, or hyphens.",
+      void 0,
+      "IDEMPOTENCY_KEY_INVALID"
+    );
+  }
+}
+function isExecutionInProgressResponse(value) {
+  return typeof value === "object" && value !== null && typeof value.executionRecovery === "object" && value.executionRecovery.state === "running";
+}
+function getExecutionRecoveryState(value) {
+  if (typeof value !== "object" || value === null || typeof value.executionRecovery !== "object") {
+    return null;
+  }
+  const state = value.executionRecovery.state;
+  return state === "running" || state === "completed" || state === "outcome_unknown" ? state : null;
+}
+function isRecoverableExecutionAttemptError(error) {
+  if (error instanceof ToolExecutionError) {
+    return error.code === "EXECUTION_IN_PROGRESS" || error.origin === "deepline" && error.category === "network" && error.networkScope === "client_to_deepline";
+  }
+  return error instanceof DeeplineError && (error.code === "EXECUTION_IN_PROGRESS" || error.code?.startsWith("NETWORK_") === true && error.statusCode === void 0);
+}
+function isRecoverableExecutionLookupError(error) {
+  if (isRecoverableExecutionAttemptError(error)) return true;
+  return error instanceof DeeplineError && (error.statusCode === 429 || error.statusCode !== void 0 && error.statusCode >= 500);
+}
+function timeoutWithinRecoveryBudget(requestTimeoutMs, defaultRequestTimeoutMs, remainingMs) {
+  return Math.min(requestTimeoutMs ?? defaultRequestTimeoutMs, remainingMs);
+}
+function executionRecoveryError(input) {
+  return new ToolExecutionError(input.message, {
+    toolId: input.toolId,
+    provider: null,
+    operation: input.toolId,
+    code: input.code,
+    origin: "deepline",
+    category: input.code === "EXECUTION_OUTCOME_UNKNOWN" ? "unknown" : "conflict",
+    retryable: input.code !== "EXECUTION_OUTCOME_UNKNOWN",
+    statusCode: null,
+    requestId: null,
+    retryAfterMs: null,
+    networkKind: null,
+    networkScope: null,
+    publicDetails: { idempotencyKey: input.idempotencyKey }
+  });
+}
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 var REGISTER_PLAY_ARTIFACTS_COMPILE_CONCURRENCY = 3;
 var REGISTER_PLAY_ARTIFACTS_MAX_BATCH_COUNT = 3;
@@ -5061,29 +5117,183 @@ var DeeplineClient = class _DeeplineClient {
    * Deepline execution envelope.
    */
   async executeTool(toolId, input, options) {
+    const inputSnapshot = JSON.parse(JSON.stringify(input));
+    const metadataSnapshot = options?.metadata ? JSON.parse(JSON.stringify(options.metadata)) : void 0;
+    const idempotencyKey = options?.idempotencyKey ?? (options?.recover ? crypto.randomUUID() : void 0);
+    if (idempotencyKey !== void 0) {
+      validateExecutionIdempotencyKey(idempotencyKey);
+      if (options?.recoveryTimeoutMs !== void 0 && (!Number.isFinite(options.recoveryTimeoutMs) || options.recoveryTimeoutMs < 0)) {
+        throw new DeeplineError(
+          "recoveryTimeoutMs must be a finite, non-negative number.",
+          void 0,
+          "IDEMPOTENCY_KEY_INVALID"
+        );
+      }
+      await options?.onExecution?.({ idempotencyKey });
+      const timeoutMs2 = options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, inputSnapshot);
+      await this.lookupExecutionByKey(idempotencyKey, timeoutMs2);
+    }
+    const timeoutMs = options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, inputSnapshot);
     const headers = {
       [EXECUTE_RESPONSE_CONTRACT_HEADER]: RAW_V2_EXECUTE_RESPONSE_CONTRACT,
       [TOOL_EXECUTION_ERROR_SCHEMA_HEADER]: String(
         TOOL_EXECUTION_ERROR_SCHEMA_VERSION
       ),
       ...options?.includeToolMetadata ? { [INCLUDE_TOOL_METADATA_HEADER]: "true" } : {},
-      [EXECUTE_RESPONSE_INTENT_HEADER]: options?.responseIntent ?? "raw"
+      [EXECUTE_RESPONSE_INTENT_HEADER]: options?.responseIntent ?? "raw",
+      ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
     };
-    const response = await this.http.post(
+    const request = (requestTimeoutMs) => this.http.post(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
       {
-        payload: input,
-        ...options?.metadata ? { metadata: options.metadata } : {}
+        payload: inputSnapshot,
+        ...metadataSnapshot ? { metadata: metadataSnapshot } : {}
       },
       headers,
       {
-        timeout: options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, input),
-        maxRetries: options?.maxRetries ?? 0,
+        timeout: requestTimeoutMs,
+        maxRetries: idempotencyKey ? 0 : options?.maxRetries ?? 0,
+        exactUrlOnly: true,
+        toolId,
+        idempotencyKey
+      }
+    );
+    let response;
+    let recoveryDeadline = null;
+    const recoveryTimeoutMs = options?.recoveryTimeoutMs ?? DEFAULT_EXECUTION_RECOVERY_TIMEOUT_MS;
+    let retryDelayMs = 1e3;
+    const recoveryTimeoutError = () => executionRecoveryError({
+      toolId,
+      idempotencyKey,
+      code: "EXECUTION_RECOVERY_TIMEOUT",
+      message: `Execution recovery for ${idempotencyKey} did not finish before the recovery timeout. Inspect client.executions.getByKey() and resume with the same idempotency key.`
+    });
+    const waitForRecoveryRetry = async (deadline) => {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) throw recoveryTimeoutError();
+      await new Promise(
+        (resolve2) => setTimeout(resolve2, Math.min(retryDelayMs, remainingMs))
+      );
+      retryDelayMs = Math.min(retryDelayMs * 2, 5e3);
+    };
+    const lookupDuringRecovery = async () => {
+      while (true) {
+        const remainingMs = recoveryDeadline - Date.now();
+        if (remainingMs <= 0) throw recoveryTimeoutError();
+        try {
+          return await this.lookupExecutionByKey(
+            idempotencyKey,
+            timeoutWithinRecoveryBudget(
+              timeoutMs,
+              this.config.timeout,
+              remainingMs
+            )
+          );
+        } catch (error) {
+          if (!isRecoverableExecutionLookupError(error)) throw error;
+          await waitForRecoveryRetry(recoveryDeadline);
+        }
+      }
+    };
+    while (true) {
+      const remainingMs = recoveryDeadline === null ? null : recoveryDeadline - Date.now();
+      if (remainingMs !== null && remainingMs <= 0) {
+        throw recoveryTimeoutError();
+      }
+      try {
+        response = await request(
+          remainingMs === null ? timeoutMs : timeoutWithinRecoveryBudget(
+            timeoutMs,
+            this.config.timeout,
+            remainingMs
+          )
+        );
+        if (getExecutionRecoveryState(response) === "outcome_unknown") {
+          if (!idempotencyKey) break;
+          throw executionRecoveryError({
+            toolId,
+            idempotencyKey,
+            code: "EXECUTION_OUTCOME_UNKNOWN",
+            message: `The outcome of execution ${idempotencyKey} is unknown. Do not retry with a new key; inspect client.executions.getByKey().`
+          });
+        }
+        if (!idempotencyKey || !isExecutionInProgressResponse(response)) {
+          break;
+        }
+        if (recoveryDeadline === null) {
+          recoveryDeadline = Date.now() + recoveryTimeoutMs;
+        }
+      } catch (error) {
+        if (idempotencyKey && error instanceof DeeplineError && error.code === "EXECUTION_OUTCOME_UNKNOWN") {
+          throw executionRecoveryError({
+            toolId,
+            idempotencyKey,
+            code: "EXECUTION_OUTCOME_UNKNOWN",
+            message: error.message
+          });
+        }
+        if (!idempotencyKey || !isRecoverableExecutionAttemptError(error)) {
+          throw error;
+        }
+        if (recoveryDeadline === null) {
+          recoveryDeadline = Date.now() + recoveryTimeoutMs;
+        }
+      }
+      await waitForRecoveryRetry(recoveryDeadline);
+      const recovered = await lookupDuringRecovery();
+      if (getExecutionRecoveryState(recovered) === "outcome_unknown") {
+        throw executionRecoveryError({
+          toolId,
+          idempotencyKey,
+          code: "EXECUTION_OUTCOME_UNKNOWN",
+          message: `The outcome of execution ${idempotencyKey} is unknown. Do not retry with a new key; inspect client.executions.getByKey().`
+        });
+      }
+    }
+    const materialized = materializeToolExecutionResponse(response);
+    return idempotencyKey ? { ...materialized, idempotencyKey } : materialized;
+  }
+  /** Read the durable state of a keyed tool execution. */
+  async getExecutionByKey(idempotencyKey) {
+    validateExecutionIdempotencyKey(idempotencyKey);
+    const result = await this.lookupExecutionByKey(idempotencyKey);
+    if (!result) {
+      throw new DeeplineError(
+        `No execution exists for idempotency key ${idempotencyKey}.`,
+        404,
+        "EXECUTION_NOT_FOUND"
+      );
+    }
+    return result;
+  }
+  async lookupExecutionByKey(idempotencyKey, timeoutMs) {
+    validateExecutionIdempotencyKey(idempotencyKey);
+    let supported = false;
+    const result = await this.http.get(
+      `/api/v2/executions/by-key/${encodeURIComponent(idempotencyKey)}`,
+      {
         exactUrlOnly: true,
-        toolId
+        maxRetries: 0,
+        timeout: timeoutMs,
+        idempotencyKey,
+        allowNotFound: true,
+        onResponse: (response) => {
+          supported = response.headers.get("X-Deepline-Idempotency-Supported") === "true";
+        }
       }
     );
-    return materializeToolExecutionResponse(response);
+    if (!supported) {
+      throw new DeeplineError(
+        "This Deepline server does not support recoverable tool executions; no tool was dispatched.",
+        422,
+        "IDEMPOTENCY_NOT_SUPPORTED"
+      );
+    }
+    return result;
+  }
+  /** Public recovery namespace. */
+  get executions() {
+    return { getByKey: (key) => this.getExecutionByKey(key) };
   }
   /**
    * Back-compatible alias for {@link executeTool}.
@@ -11170,10 +11380,11 @@ var DeeplineContext = class {
       /** Get detailed metadata for a tool. */
       get: (toolId) => this.client.getTool(toolId),
       /** Execute a tool and return the standard execution envelope. */
-      execute: async (toolId, input) => {
+      execute: async (toolId, input, options) => {
         const response = await this.client.executeTool(toolId, input, {
           includeToolMetadata: true,
-          responseIntent: "dataset"
+          responseIntent: "dataset",
+          ...options
         });
         return toolExecutionEnvelopeToResult(toolId, response, {
           client: this.client,
@@ -11182,6 +11393,10 @@ var DeeplineContext = class {
       }
     };
   }
+  /** Durable state for recoverable direct tool executions. */
+  get executions() {
+    return { getByKey: (key) => this.client.getExecutionByKey(key) };
+  }
   /**
    * Play discovery and named-play handles.
    *
@@ -11489,7 +11704,7 @@ function toolExecutionEnvelopeToResult(fallbackToolId, response, options) {
   const meta = response.toolResponse?.meta;
   const metadata = isRecord9(response._metadata) ? response._metadata.tool : null;
   const toolMetadata = isRecord9(metadata) ? metadata : {};
-  return attachSdkQueryResultDatasetResult(
+  const result = attachSdkQueryResultDatasetResult(
     fallbackToolId,
     createToolExecuteResult({
       status: typeof response.status === "string" ? response.status : "completed",
@@ -11522,6 +11737,14 @@ function toolExecutionEnvelopeToResult(fallbackToolId, response, options) {
     }),
     options
   );
+  const executionRecovery = isRecord9(response.executionRecovery) ? response.executionRecovery : void 0;
+  if (typeof response.idempotencyKey === "string") {
+    result.idempotencyKey = response.idempotencyKey;
+  }
+  if (executionRecovery) {
+    result.executionRecovery = executionRecovery;
+  }
+  return result;
 }
 function defineInput(schema) {
   return createPlayInputContract(schema);

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.148";
+    readonly version: "0.3.150";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.d.ts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.148";
+    readonly version: "0.3.150";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.js

@@ -74,7 +74,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.148",
+  version: "0.3.150",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/release.mjs

@@ -48,7 +48,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.148",
+  version: "0.3.150",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.148",
+  "version": "0.3.150",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",