deepline 0.3.238 → 0.3.240

package/dist/cli/index.js

@@ -3001,6 +3001,12 @@ function resolveCliCommandContext(inputConfig, requestedScope) {
   };
 }
 
+// ../integration-contracts/opensosdata/execution-policy.ts
+var OPENSOSDATA_LOOKUP_REQUEST_TIMEOUT_MS = 12e4;
+var OPENSOSDATA_POLL_INTERVAL_MS = 3e3;
+var OPENSOSDATA_POLL_TIMEOUT_MS = 9e4;
+var OPENSOSDATA_LOOKUP_CLIENT_TIMEOUT_MS = 6e4 + OPENSOSDATA_LOOKUP_REQUEST_TIMEOUT_MS + OPENSOSDATA_POLL_TIMEOUT_MS + OPENSOSDATA_POLL_INTERVAL_MS + OPENSOSDATA_LOOKUP_REQUEST_TIMEOUT_MS + 15e3;
+
 // ../integration-contracts/theirstack/execution-policy.ts
 var THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS = 135e3;
 var THEIRSTACK_SLOW_JOB_SEARCH_CLIENT_TIMEOUT_MS = 6e4 + THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS + 15e3;
@@ -3151,6 +3157,9 @@ var APIFY_SYNC_DEFAULT_TIMEOUT_MS = 3e5;
 var APIFY_SYNC_RESPONSE_GRACE_MS = 9e4;
 function resolveToolExecuteTimeoutMs(toolId, input2) {
   const normalized = toolId.trim().toLowerCase();
+  if (normalized === "opensosdata_business_lookup") {
+    return OPENSOSDATA_LOOKUP_CLIENT_TIMEOUT_MS;
+  }
   if (normalized === "apify_run_actor_sync") {
     const requestedTimeoutMs = input2.timeoutMs ?? APIFY_SYNC_DEFAULT_TIMEOUT_MS;
     if (typeof requestedTimeoutMs === "number" && Number.isFinite(requestedTimeoutMs) && requestedTimeoutMs > 0) {
@@ -3454,7 +3463,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.238",
+  version: "0.3.240",
   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
@@ -4246,6 +4255,7 @@ var HttpClient = class {
     let fetchAttempts = 0;
     let lastRequestUrl = url;
     let networkFailedAt;
+    let networkPhase = "before_request";
     const headers = this.authHeaders(options?.headers);
     if (options?.body !== void 0) {
       headers["Content-Type"] = "application/json";
@@ -4264,6 +4274,7 @@ var HttpClient = class {
         const backoffMs = Math.min(1e3 * Math.pow(2, attempt - 1), 3e4);
         const delayMs = retryAfterDelayMs === null ? backoffMs : Math.max(backoffMs, retryAfterDelayMs);
         retryAfterDelayMs = null;
+        networkPhase = "retry_wait";
         try {
           await sleep(delayMs, options?.signal);
         } catch (error) {
@@ -4289,16 +4300,19 @@ var HttpClient = class {
         options?.signal?.addEventListener("abort", abortRequest, {
           once: true
         });
+        networkPhase = "before_request";
         try {
           const requestBody = options?.formData !== void 0 ? typeof options.formData === "function" ? options.formData() : options.formData : options?.body !== void 0 ? JSON.stringify(options.body) : void 0;
           fetchAttempts += 1;
           lastRequestUrl = candidateUrl;
+          networkPhase = "awaiting_headers";
           const response = await fetch(candidateUrl, {
             method,
             headers,
             body: requestBody,
             signal: controller.signal
           });
+          networkPhase = "reading_body";
           options?.onResponse?.(response);
           if (response.status === 404 && options?.allowNotFound) {
             clearTimeout(timeoutId);
@@ -4441,7 +4455,8 @@ var HttpClient = class {
         failedAtUtc: new Date(failedAt).toISOString(),
         // Elapsed time covers the entire logical request, including retries.
         elapsedMs: Math.max(0, failedAt - requestStartedAt),
-        attempts: fetchAttempts
+        attempts: fetchAttempts,
+        phase: networkPhase
       }
     };
     if (options?.toolId) {
@@ -6340,7 +6355,7 @@ var DeeplineClient = class _DeeplineClient {
       purchaseCredits: (options2) => this.purchaseTargetBillingCredits(options2),
       recoverCreditPurchase: (options2) => this.recoverTargetBillingCreditPurchase(options2),
       transitionPlan: (options2) => this.transitionTargetBillingPlan(options2),
-      portalSession: () => this.createTargetBillingPortalSession()
+      portalSession: (options2) => this.createTargetBillingPortalSession(options2)
     };
     this.workspaces = {
       create: (options2) => this.createWorkspace(options2)
@@ -8861,8 +8876,11 @@ var DeeplineClient = class _DeeplineClient {
     );
   }
   /** Create a Stripe-hosted portal session for payment recovery and invoices. */
-  async createTargetBillingPortalSession() {
-    const response = await this.http.post("/api/v2/billing/portal-sessions", {});
+  async createTargetBillingPortalSession(options) {
+    const response = await this.http.post(
+      options?.flow === "customer_update" ? "/api/v2/billing/portal-sessions?flow=customer_update" : "/api/v2/billing/portal-sessions",
+      {}
+    );
     return response.data;
   }
   /** Create an additional workspace through the durable PAYG workflow. */
@@ -12577,7 +12595,9 @@ async function handleTargetPlanCancellation(options) {
   );
 }
 async function handleTargetPortal(options) {
-  const payload = await new DeeplineClient().billing.portalSession();
+  const payload = await new DeeplineClient().billing.portalSession(
+    options.billingAddress ? { flow: "customer_update" } : void 0
+  );
   if (!options.json && !options.noOpen) openInBrowser(payload.url);
   printCommandEnvelope({ ok: true, ...payload }, { json: options.json });
 }
@@ -12864,7 +12884,7 @@ Examples:
     "Invoice recipient when the account has no billing email"
   ).option("--idempotency-key <key>", "Stable retry key").option("--json", "Emit JSON output").action(handleTargetPlan);
   billing.command("cancel-plan").description("Cancel a target subscription at period end, or undo it.").option("--undo", "Undo a pending period-end cancellation").option("--idempotency-key <key>", "Stable retry key").option("--json", "Emit JSON output").action(handleTargetPlanCancellation);
-  billing.command("portal").description("Open the Stripe-hosted billing recovery portal.").option("--no-open", "Print the URL without opening a browser").option("--json", "Emit JSON output").action(handleTargetPortal);
+  billing.command("portal").description("Open the Stripe-hosted billing recovery portal.").option("--billing-address", "Open the billing address editor directly").option("--no-open", "Print the URL without opening a browser").option("--json", "Emit JSON output").action(handleTargetPortal);
   billing.command("plans").description("Show published plans and the plan you are on.").addHelpText(
     "after",
     `
@@ -43168,7 +43188,7 @@ function classifyNetworkFailure(error) {
     if (combined.includes("aborterror") || combined.includes("timeout") || combined.includes("timed out") || combined.includes("etimedout")) {
       return "network_timeout";
     }
-    if (combined.includes("enotfound") || combined.includes("eai_again") || combined.includes("name or service not known") || combined.includes("temporary failure in name resolution")) {
+    if (combined.includes("enotfound") || combined.includes("eai_again") || combined.includes("getaddrinfo") || combined.includes("name or service not known") || combined.includes("temporary failure in name resolution")) {
       return "network_dns_resolution_failed";
     }
     if (combined.includes("econnrefused") || combined.includes("connection refused")) {
@@ -43191,6 +43211,14 @@ function classifyNetworkFailure(error) {
   return "network_error";
 }
 function classifyNetworkCauseCategory(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let cause = error;
+  while (cause && typeof cause === "object" && !seen.has(cause)) {
+    seen.add(cause);
+    const record3 = cause;
+    if (record3.code === "UND_ERR_CONNECT_TIMEOUT") return "connect_timeout";
+    cause = record3.cause;
+  }
   switch (classifyNetworkFailure(error)) {
     case "network_dns_resolution_failed":
       return "dns";
@@ -43199,7 +43227,7 @@ function classifyNetworkCauseCategory(error) {
     case "network_connection_reset":
       return "reset";
     case "network_timeout":
-      return "connect_timeout";
+      return "timeout";
     default:
       return "unknown";
   }
@@ -43365,8 +43393,44 @@ function resolveSdkCliFailureExitCode(error) {
 function resolvedFailureKind(input2) {
   return input2.error === void 0 ? "command_exit" : "uncaught_exception";
 }
+function safeRequestDiagnostics(error) {
+  if (!(error instanceof DeeplineError)) return null;
+  const request = error.details?.request;
+  if (!request || typeof request !== "object" || Array.isArray(request))
+    return null;
+  const value = request;
+  const result = {};
+  if (typeof value.phase === "string" && [
+    "before_request",
+    "retry_wait",
+    "awaiting_headers",
+    "reading_body"
+  ].includes(value.phase))
+    result.phase = value.phase;
+  if (typeof value.method === "string" && /^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$/.test(value.method))
+    result.method = value.method;
+  if (typeof value.url === "string") {
+    try {
+      const url = new URL(value.url);
+      if (url.protocol === "https:" || url.protocol === "http:") {
+        result.url = redactFailureText(`${url.origin}${url.pathname}`, 1e3);
+      }
+    } catch {
+    }
+  }
+  if (typeof value.failedAtUtc === "string" && Number.isFinite(Date.parse(value.failedAtUtc))) {
+    result.failedAtUtc = new Date(value.failedAtUtc).toISOString();
+  }
+  for (const key of ["elapsedMs", "attempts"]) {
+    const number = value[key];
+    if (typeof number === "number" && Number.isSafeInteger(number) && number >= 0)
+      result[key] = number;
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
 function buildFailureReport(input2) {
   const durationMs = Math.max(0, Date.now() - input2.startedAtMs);
+  const request = safeRequestDiagnostics(input2.error);
   const failureKind = resolvedFailureKind({
     exitCode: input2.exitCode,
     error: input2.error
@@ -43391,6 +43455,7 @@ function buildFailureReport(input2) {
       base_url: redactFailureText(input2.baseUrl, 400),
       command_summary: sanitizeCommand(input2.argv),
       environment: buildEnvironmentContext(),
+      ...request ? { request } : {},
       failure_kind: failureKind,
       failure_code: code,
       failure_stage: input2.error === void 0 ? "command_exit" : "cli_main",
@@ -49438,6 +49503,7 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
   const outputSchemaRecord = recordField2(tool, "outputSchema", "output_schema");
   const outputFields = toolOutputFieldsForDisplay(outputSchemaRecord);
   const usageGuidance = recordField2(tool, "usageGuidance", "usage_guidance");
+  const guidance = recordField2(tool, "guidance");
   const toolExecutionResult = recordField2(
     usageGuidance,
     "toolExecutionResult",
@@ -49486,6 +49552,7 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
     displayName: tool.displayName,
     cost: pricing,
     description: tool.description,
+    ...Object.keys(guidance).length > 0 ? { guidance } : {},
     categories: tool.categories,
     ...deprecated ? {
       deprecated: true,
@@ -49636,6 +49703,15 @@ function printMonitorTypeContract(tool, requestedToolId) {
   console.log("");
   console.log(`More: deepline tools get ${toolId} --json`);
 }
+function toolGuidanceLines(guidance) {
+  const record3 = isRecord9(guidance) ? guidance : {};
+  const toolGuidance = stringField2(record3, "tool");
+  const providerGuidance = stringField2(record3, "provider");
+  return [
+    ...toolGuidance ? [`- This tool: ${toolGuidance}`] : [],
+    ...providerGuidance ? [`- Provider: ${providerGuidance}`] : []
+  ];
+}
 function printCompactToolContract(tool, requestedToolId) {
   if (isMonitorTypeTool(tool)) {
     printMonitorTypeContract(tool, requestedToolId);
@@ -49657,6 +49733,10 @@ function printCompactToolContract(tool, requestedToolId) {
   if (Array.isArray(contract.categories) && contract.categories.length) {
     console.log(`Tags: ${contract.categories.join(", ")}`);
   }
+  const guidanceLines = toolGuidanceLines(contract.guidance);
+  if (guidanceLines.length > 0) {
+    console.log(["Guidance:", ...guidanceLines].join("\n"));
+  }
   printToolOutputArrayShape(contract);
   printToolExecutionHints(contract);
   if (contract.deprecated === true) {
@@ -50724,6 +50804,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
 }
 function buildToolExecuteBaseEnvelope(input2) {
   const envelope = commandEnvelopeFromRawResponse(input2.rawResponse);
+  const guidanceLines = toolExecuteExitCode(envelope) !== 0 || input2.listExpected === true && !input2.listConversion ? toolGuidanceLines(input2.guidance) : [];
   const warningMessages = extractToolExecutionWarningMessages(
     input2.rawResponse
   );
@@ -50775,6 +50856,7 @@ function buildToolExecuteBaseEnvelope(input2) {
       inspect: inspectCommand,
       ...billingLookup ? { billing: billingLookup } : {},
       ...apifyRecovery ?? {},
+      ...guidanceLines.length > 0 ? { guidance: input2.guidance } : {},
       playDebugging: "When fixing a play getter, inspect returned dataset handles with runs get and export rows with runs export; do not copy CLI preview paths blindly.",
       ...input2.listConversion ? {
         expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again.",
@@ -50802,7 +50884,8 @@ function buildToolExecuteBaseEnvelope(input2) {
           ] : summaryEntries.length > 0 ? summaryEntries.map(
             ([key, value]) => `${key}=${String(value)}`
           ) : [JSON.stringify(input2.rawResponse, null, 2)]
-        }
+        },
+        ...guidanceLines.length > 0 ? [{ title: "guidance", lines: guidanceLines }] : []
       ],
       actions
     }
@@ -50974,10 +51057,17 @@ async function executeTool(args) {
     ...idempotencyKey ? { idempotencyKey } : {},
     ...parsed.recoveryTimeoutMs !== void 0 ? { recoveryTimeoutMs: parsed.recoveryTimeoutMs } : {},
     searchRef: recentSearchRef()
+  }).catch((error) => {
+    const guidanceLines = toolGuidanceLines(metadata.guidance);
+    if (guidanceLines.length > 0) {
+      console.error(
+        [`Guidance for ${parsed.toolId}:`, ...guidanceLines].join("\n")
+      );
+    }
+    throw error;
   });
-  const listConversion = tryConvertToList(rawResponse, {
-    listExtractorPaths: listExtractorPathsFromUsageGuidance(metadata)
-  });
+  const listExtractorPaths = listExtractorPathsFromUsageGuidance(metadata);
+  const listConversion = tryConvertToList(rawResponse, { listExtractorPaths });
   const summary = extractSummaryFields(rawResponse);
   const baseEnvelope = buildToolExecuteBaseEnvelope({
     toolId: parsed.toolId,
@@ -50985,7 +51075,9 @@ async function executeTool(args) {
     ...idempotencyKey ? { idempotencyKey } : {},
     rawResponse,
     listConversion,
-    summary
+    summary,
+    guidance: metadata.guidance,
+    listExpected: listExtractorPaths.length > 0
   });
   const executeExitCode = toolExecuteExitCode(baseEnvelope);
   const delivered = (() => {

package/dist/cli/index.mjs

@@ -2996,6 +2996,12 @@ function resolveCliCommandContext(inputConfig, requestedScope) {
   };
 }
 
+// ../integration-contracts/opensosdata/execution-policy.ts
+var OPENSOSDATA_LOOKUP_REQUEST_TIMEOUT_MS = 12e4;
+var OPENSOSDATA_POLL_INTERVAL_MS = 3e3;
+var OPENSOSDATA_POLL_TIMEOUT_MS = 9e4;
+var OPENSOSDATA_LOOKUP_CLIENT_TIMEOUT_MS = 6e4 + OPENSOSDATA_LOOKUP_REQUEST_TIMEOUT_MS + OPENSOSDATA_POLL_TIMEOUT_MS + OPENSOSDATA_POLL_INTERVAL_MS + OPENSOSDATA_LOOKUP_REQUEST_TIMEOUT_MS + 15e3;
+
 // ../integration-contracts/theirstack/execution-policy.ts
 var THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS = 135e3;
 var THEIRSTACK_SLOW_JOB_SEARCH_CLIENT_TIMEOUT_MS = 6e4 + THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS + 15e3;
@@ -3146,6 +3152,9 @@ var APIFY_SYNC_DEFAULT_TIMEOUT_MS = 3e5;
 var APIFY_SYNC_RESPONSE_GRACE_MS = 9e4;
 function resolveToolExecuteTimeoutMs(toolId, input2) {
   const normalized = toolId.trim().toLowerCase();
+  if (normalized === "opensosdata_business_lookup") {
+    return OPENSOSDATA_LOOKUP_CLIENT_TIMEOUT_MS;
+  }
   if (normalized === "apify_run_actor_sync") {
     const requestedTimeoutMs = input2.timeoutMs ?? APIFY_SYNC_DEFAULT_TIMEOUT_MS;
     if (typeof requestedTimeoutMs === "number" && Number.isFinite(requestedTimeoutMs) && requestedTimeoutMs > 0) {
@@ -3449,7 +3458,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.238",
+  version: "0.3.240",
   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
@@ -4241,6 +4250,7 @@ var HttpClient = class {
     let fetchAttempts = 0;
     let lastRequestUrl = url;
     let networkFailedAt;
+    let networkPhase = "before_request";
     const headers = this.authHeaders(options?.headers);
     if (options?.body !== void 0) {
       headers["Content-Type"] = "application/json";
@@ -4259,6 +4269,7 @@ var HttpClient = class {
         const backoffMs = Math.min(1e3 * Math.pow(2, attempt - 1), 3e4);
         const delayMs = retryAfterDelayMs === null ? backoffMs : Math.max(backoffMs, retryAfterDelayMs);
         retryAfterDelayMs = null;
+        networkPhase = "retry_wait";
         try {
           await sleep(delayMs, options?.signal);
         } catch (error) {
@@ -4284,16 +4295,19 @@ var HttpClient = class {
         options?.signal?.addEventListener("abort", abortRequest, {
           once: true
         });
+        networkPhase = "before_request";
         try {
           const requestBody = options?.formData !== void 0 ? typeof options.formData === "function" ? options.formData() : options.formData : options?.body !== void 0 ? JSON.stringify(options.body) : void 0;
           fetchAttempts += 1;
           lastRequestUrl = candidateUrl;
+          networkPhase = "awaiting_headers";
           const response = await fetch(candidateUrl, {
             method,
             headers,
             body: requestBody,
             signal: controller.signal
           });
+          networkPhase = "reading_body";
           options?.onResponse?.(response);
           if (response.status === 404 && options?.allowNotFound) {
             clearTimeout(timeoutId);
@@ -4436,7 +4450,8 @@ var HttpClient = class {
         failedAtUtc: new Date(failedAt).toISOString(),
         // Elapsed time covers the entire logical request, including retries.
         elapsedMs: Math.max(0, failedAt - requestStartedAt),
-        attempts: fetchAttempts
+        attempts: fetchAttempts,
+        phase: networkPhase
       }
     };
     if (options?.toolId) {
@@ -6335,7 +6350,7 @@ var DeeplineClient = class _DeeplineClient {
       purchaseCredits: (options2) => this.purchaseTargetBillingCredits(options2),
       recoverCreditPurchase: (options2) => this.recoverTargetBillingCreditPurchase(options2),
       transitionPlan: (options2) => this.transitionTargetBillingPlan(options2),
-      portalSession: () => this.createTargetBillingPortalSession()
+      portalSession: (options2) => this.createTargetBillingPortalSession(options2)
     };
     this.workspaces = {
       create: (options2) => this.createWorkspace(options2)
@@ -8856,8 +8871,11 @@ var DeeplineClient = class _DeeplineClient {
     );
   }
   /** Create a Stripe-hosted portal session for payment recovery and invoices. */
-  async createTargetBillingPortalSession() {
-    const response = await this.http.post("/api/v2/billing/portal-sessions", {});
+  async createTargetBillingPortalSession(options) {
+    const response = await this.http.post(
+      options?.flow === "customer_update" ? "/api/v2/billing/portal-sessions?flow=customer_update" : "/api/v2/billing/portal-sessions",
+      {}
+    );
     return response.data;
   }
   /** Create an additional workspace through the durable PAYG workflow. */
@@ -12584,7 +12602,9 @@ async function handleTargetPlanCancellation(options) {
   );
 }
 async function handleTargetPortal(options) {
-  const payload = await new DeeplineClient().billing.portalSession();
+  const payload = await new DeeplineClient().billing.portalSession(
+    options.billingAddress ? { flow: "customer_update" } : void 0
+  );
   if (!options.json && !options.noOpen) openInBrowser(payload.url);
   printCommandEnvelope({ ok: true, ...payload }, { json: options.json });
 }
@@ -12871,7 +12891,7 @@ Examples:
     "Invoice recipient when the account has no billing email"
   ).option("--idempotency-key <key>", "Stable retry key").option("--json", "Emit JSON output").action(handleTargetPlan);
   billing.command("cancel-plan").description("Cancel a target subscription at period end, or undo it.").option("--undo", "Undo a pending period-end cancellation").option("--idempotency-key <key>", "Stable retry key").option("--json", "Emit JSON output").action(handleTargetPlanCancellation);
-  billing.command("portal").description("Open the Stripe-hosted billing recovery portal.").option("--no-open", "Print the URL without opening a browser").option("--json", "Emit JSON output").action(handleTargetPortal);
+  billing.command("portal").description("Open the Stripe-hosted billing recovery portal.").option("--billing-address", "Open the billing address editor directly").option("--no-open", "Print the URL without opening a browser").option("--json", "Emit JSON output").action(handleTargetPortal);
   billing.command("plans").description("Show published plans and the plan you are on.").addHelpText(
     "after",
     `
@@ -43278,7 +43298,7 @@ function classifyNetworkFailure(error) {
     if (combined.includes("aborterror") || combined.includes("timeout") || combined.includes("timed out") || combined.includes("etimedout")) {
       return "network_timeout";
     }
-    if (combined.includes("enotfound") || combined.includes("eai_again") || combined.includes("name or service not known") || combined.includes("temporary failure in name resolution")) {
+    if (combined.includes("enotfound") || combined.includes("eai_again") || combined.includes("getaddrinfo") || combined.includes("name or service not known") || combined.includes("temporary failure in name resolution")) {
       return "network_dns_resolution_failed";
     }
     if (combined.includes("econnrefused") || combined.includes("connection refused")) {
@@ -43301,6 +43321,14 @@ function classifyNetworkFailure(error) {
   return "network_error";
 }
 function classifyNetworkCauseCategory(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let cause = error;
+  while (cause && typeof cause === "object" && !seen.has(cause)) {
+    seen.add(cause);
+    const record3 = cause;
+    if (record3.code === "UND_ERR_CONNECT_TIMEOUT") return "connect_timeout";
+    cause = record3.cause;
+  }
   switch (classifyNetworkFailure(error)) {
     case "network_dns_resolution_failed":
       return "dns";
@@ -43309,7 +43337,7 @@ function classifyNetworkCauseCategory(error) {
     case "network_connection_reset":
       return "reset";
     case "network_timeout":
-      return "connect_timeout";
+      return "timeout";
     default:
       return "unknown";
   }
@@ -43475,8 +43503,44 @@ function resolveSdkCliFailureExitCode(error) {
 function resolvedFailureKind(input2) {
   return input2.error === void 0 ? "command_exit" : "uncaught_exception";
 }
+function safeRequestDiagnostics(error) {
+  if (!(error instanceof DeeplineError)) return null;
+  const request = error.details?.request;
+  if (!request || typeof request !== "object" || Array.isArray(request))
+    return null;
+  const value = request;
+  const result = {};
+  if (typeof value.phase === "string" && [
+    "before_request",
+    "retry_wait",
+    "awaiting_headers",
+    "reading_body"
+  ].includes(value.phase))
+    result.phase = value.phase;
+  if (typeof value.method === "string" && /^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$/.test(value.method))
+    result.method = value.method;
+  if (typeof value.url === "string") {
+    try {
+      const url = new URL(value.url);
+      if (url.protocol === "https:" || url.protocol === "http:") {
+        result.url = redactFailureText(`${url.origin}${url.pathname}`, 1e3);
+      }
+    } catch {
+    }
+  }
+  if (typeof value.failedAtUtc === "string" && Number.isFinite(Date.parse(value.failedAtUtc))) {
+    result.failedAtUtc = new Date(value.failedAtUtc).toISOString();
+  }
+  for (const key of ["elapsedMs", "attempts"]) {
+    const number = value[key];
+    if (typeof number === "number" && Number.isSafeInteger(number) && number >= 0)
+      result[key] = number;
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
 function buildFailureReport(input2) {
   const durationMs = Math.max(0, Date.now() - input2.startedAtMs);
+  const request = safeRequestDiagnostics(input2.error);
   const failureKind = resolvedFailureKind({
     exitCode: input2.exitCode,
     error: input2.error
@@ -43501,6 +43565,7 @@ function buildFailureReport(input2) {
       base_url: redactFailureText(input2.baseUrl, 400),
       command_summary: sanitizeCommand(input2.argv),
       environment: buildEnvironmentContext(),
+      ...request ? { request } : {},
       failure_kind: failureKind,
       failure_code: code,
       failure_stage: input2.error === void 0 ? "command_exit" : "cli_main",
@@ -49591,6 +49656,7 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
   const outputSchemaRecord = recordField2(tool, "outputSchema", "output_schema");
   const outputFields = toolOutputFieldsForDisplay(outputSchemaRecord);
   const usageGuidance = recordField2(tool, "usageGuidance", "usage_guidance");
+  const guidance = recordField2(tool, "guidance");
   const toolExecutionResult = recordField2(
     usageGuidance,
     "toolExecutionResult",
@@ -49639,6 +49705,7 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
     displayName: tool.displayName,
     cost: pricing,
     description: tool.description,
+    ...Object.keys(guidance).length > 0 ? { guidance } : {},
     categories: tool.categories,
     ...deprecated ? {
       deprecated: true,
@@ -49789,6 +49856,15 @@ function printMonitorTypeContract(tool, requestedToolId) {
   console.log("");
   console.log(`More: deepline tools get ${toolId} --json`);
 }
+function toolGuidanceLines(guidance) {
+  const record3 = isRecord9(guidance) ? guidance : {};
+  const toolGuidance = stringField2(record3, "tool");
+  const providerGuidance = stringField2(record3, "provider");
+  return [
+    ...toolGuidance ? [`- This tool: ${toolGuidance}`] : [],
+    ...providerGuidance ? [`- Provider: ${providerGuidance}`] : []
+  ];
+}
 function printCompactToolContract(tool, requestedToolId) {
   if (isMonitorTypeTool(tool)) {
     printMonitorTypeContract(tool, requestedToolId);
@@ -49810,6 +49886,10 @@ function printCompactToolContract(tool, requestedToolId) {
   if (Array.isArray(contract.categories) && contract.categories.length) {
     console.log(`Tags: ${contract.categories.join(", ")}`);
   }
+  const guidanceLines = toolGuidanceLines(contract.guidance);
+  if (guidanceLines.length > 0) {
+    console.log(["Guidance:", ...guidanceLines].join("\n"));
+  }
   printToolOutputArrayShape(contract);
   printToolExecutionHints(contract);
   if (contract.deprecated === true) {
@@ -50877,6 +50957,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
 }
 function buildToolExecuteBaseEnvelope(input2) {
   const envelope = commandEnvelopeFromRawResponse(input2.rawResponse);
+  const guidanceLines = toolExecuteExitCode(envelope) !== 0 || input2.listExpected === true && !input2.listConversion ? toolGuidanceLines(input2.guidance) : [];
   const warningMessages = extractToolExecutionWarningMessages(
     input2.rawResponse
   );
@@ -50928,6 +51009,7 @@ function buildToolExecuteBaseEnvelope(input2) {
       inspect: inspectCommand,
       ...billingLookup ? { billing: billingLookup } : {},
       ...apifyRecovery ?? {},
+      ...guidanceLines.length > 0 ? { guidance: input2.guidance } : {},
       playDebugging: "When fixing a play getter, inspect returned dataset handles with runs get and export rows with runs export; do not copy CLI preview paths blindly.",
       ...input2.listConversion ? {
         expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again.",
@@ -50955,7 +51037,8 @@ function buildToolExecuteBaseEnvelope(input2) {
           ] : summaryEntries.length > 0 ? summaryEntries.map(
             ([key, value]) => `${key}=${String(value)}`
           ) : [JSON.stringify(input2.rawResponse, null, 2)]
-        }
+        },
+        ...guidanceLines.length > 0 ? [{ title: "guidance", lines: guidanceLines }] : []
       ],
       actions
     }
@@ -51127,10 +51210,17 @@ async function executeTool(args) {
     ...idempotencyKey ? { idempotencyKey } : {},
     ...parsed.recoveryTimeoutMs !== void 0 ? { recoveryTimeoutMs: parsed.recoveryTimeoutMs } : {},
     searchRef: recentSearchRef()
+  }).catch((error) => {
+    const guidanceLines = toolGuidanceLines(metadata.guidance);
+    if (guidanceLines.length > 0) {
+      console.error(
+        [`Guidance for ${parsed.toolId}:`, ...guidanceLines].join("\n")
+      );
+    }
+    throw error;
   });
-  const listConversion = tryConvertToList(rawResponse, {
-    listExtractorPaths: listExtractorPathsFromUsageGuidance(metadata)
-  });
+  const listExtractorPaths = listExtractorPathsFromUsageGuidance(metadata);
+  const listConversion = tryConvertToList(rawResponse, { listExtractorPaths });
   const summary = extractSummaryFields(rawResponse);
   const baseEnvelope = buildToolExecuteBaseEnvelope({
     toolId: parsed.toolId,
@@ -51138,7 +51228,9 @@ async function executeTool(args) {
     ...idempotencyKey ? { idempotencyKey } : {},
     rawResponse,
     listConversion,
-    summary
+    summary,
+    guidance: metadata.guidance,
+    listExpected: listExtractorPaths.length > 0
   });
   const executeExitCode = toolExecuteExitCode(baseEnvelope);
   const delivered = (() => {

package/dist/index.d.mts

@@ -1269,6 +1269,11 @@ interface ToolDefinition extends ToolExecutionMetadataFields {
     outputSchema?: Record<string, unknown>;
     /** User-facing pricing summary. Internal provider/settlement costs are intentionally omitted. */
     pricing?: ToolPricingSummary | null;
+    /** How to use the tool well: the provider's summary and the tool's own notes. */
+    guidance?: {
+        provider?: string;
+        tool?: string;
+    };
     /** Copyable play-runtime guidance for V2 tool execution results. */
     usageGuidance?: {
         execute?: string;
@@ -4533,6 +4538,15 @@ type TargetBillingStatusResult = {
     payment_state: string;
     recharge_state: string;
     billing_email?: string | null;
+    /** Omitted when unavailable; null when no address has been saved. */
+    billing_address?: {
+        line1: string | null;
+        line2: string | null;
+        city: string | null;
+        state: string | null;
+        postal_code: string | null;
+        country: string | null;
+    } | null;
     collection_method?: 'charge_automatically' | 'send_invoice';
     payment_access_policy?: 'payment_required' | 'net_30' | 'net_60';
     plan_invoice?: {
@@ -4863,7 +4877,9 @@ type BillingNamespace = {
     /** Start, change, cancel, or undo a target plan transition. */
     transitionPlan: (options: TargetBillingPlanTransitionOptions) => Promise<TargetBillingMutationResult>;
     /** Create a Stripe-hosted billing Portal session. */
-    portalSession: () => Promise<{
+    portalSession: (options?: {
+        flow?: 'customer_update';
+    }) => Promise<{
         url: string;
     }>;
 };
@@ -6022,7 +6038,9 @@ declare class DeeplineClient {
      */
     transitionTargetBillingPlan(options: TargetBillingPlanTransitionOptions): Promise<TargetBillingMutationResult>;
     /** Create a Stripe-hosted portal session for payment recovery and invoices. */
-    createTargetBillingPortalSession(): Promise<{
+    createTargetBillingPortalSession(options?: {
+        flow?: 'customer_update';
+    }): Promise<{
         url: string;
     }>;
     /** Create an additional workspace through the durable PAYG workflow. */