deepline 0.3.238 → 0.3.240

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

@@ -1806,6 +1806,15 @@ export 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?: {
@@ -2163,7 +2172,9 @@ export type BillingNamespace = {
     options: TargetBillingPlanTransitionOptions,
   ) => Promise<TargetBillingMutationResult>;
   /** Create a Stripe-hosted billing Portal session. */
-  portalSession: () => Promise<{ url: string }>;
+  portalSession: (options?: {
+    flow?: 'customer_update';
+  }) => Promise<{ url: string }>;
 };
 
 function requireTargetBillingIdempotencyKey(value: string): string {
@@ -2713,7 +2724,8 @@ export class DeeplineClient {
       recoverCreditPurchase: (options) =>
         this.recoverTargetBillingCreditPurchase(options),
       transitionPlan: (options) => this.transitionTargetBillingPlan(options),
-      portalSession: () => this.createTargetBillingPortalSession(),
+      portalSession: (options) =>
+        this.createTargetBillingPortalSession(options),
     };
     this.workspaces = {
       create: (options) => this.createWorkspace(options),
@@ -6154,11 +6166,18 @@ export class DeeplineClient {
   }
 
   /** Create a Stripe-hosted portal session for payment recovery and invoices. */
-  async createTargetBillingPortalSession(): Promise<{ url: string }> {
+  async createTargetBillingPortalSession(options?: {
+    flow?: 'customer_update';
+  }): Promise<{ url: string }> {
     const response = await this.http.post<{
       data: { url: string };
       request_id?: string;
-    }>('/api/v2/billing/portal-sessions', {});
+    }>(
+      options?.flow === 'customer_update'
+        ? '/api/v2/billing/portal-sessions?flow=customer_update'
+        : '/api/v2/billing/portal-sessions',
+      {},
+    );
     return response.data;
   }
 

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

@@ -395,6 +395,11 @@ export class HttpClient {
     let fetchAttempts = 0;
     let lastRequestUrl = url;
     let networkFailedAt: number | undefined;
+    let networkPhase:
+      | 'before_request'
+      | 'retry_wait'
+      | 'awaiting_headers'
+      | 'reading_body' = 'before_request';
 
     const headers = this.authHeaders(options?.headers);
 
@@ -423,6 +428,7 @@ export class HttpClient {
             ? backoffMs
             : Math.max(backoffMs, retryAfterDelayMs);
         retryAfterDelayMs = null;
+        networkPhase = 'retry_wait';
         try {
           await sleep(delayMs, options?.signal);
         } catch (error) {
@@ -450,6 +456,7 @@ export class HttpClient {
           once: true,
         });
 
+        networkPhase = 'before_request';
         try {
           const requestBody =
             options?.formData !== undefined
@@ -461,6 +468,7 @@ export class HttpClient {
                 : undefined;
           fetchAttempts += 1;
           lastRequestUrl = candidateUrl;
+          networkPhase = 'awaiting_headers';
           const response = await fetch(candidateUrl, {
             method,
             headers,
@@ -468,6 +476,7 @@ export class HttpClient {
             signal: controller.signal,
           });
 
+          networkPhase = 'reading_body';
           options?.onResponse?.(response);
           if (response.status === 404 && options?.allowNotFound) {
             clearTimeout(timeoutId);
@@ -671,6 +680,7 @@ export class HttpClient {
         // Elapsed time covers the entire logical request, including retries.
         elapsedMs: Math.max(0, failedAt - requestStartedAt),
         attempts: fetchAttempts,
+        phase: networkPhase,
       },
     };
     if (options?.toolId) {

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

@@ -200,7 +200,7 @@ export const 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: {

package/dist/bundling-sources/sdk/src/tool-calls.ts

@@ -1,3 +1,4 @@
+import { OPENSOSDATA_LOOKUP_CLIENT_TIMEOUT_MS } from '../../shared_libs/integration-contracts/opensosdata/execution-policy.js';
 import type { ToolResultBilling } from '../../shared_libs/plays/tool-result-types.js';
 import { resolveTheirstackClientTimeoutMs } from '../../shared_libs/integration-contracts/theirstack/execution-policy.js';
 import { resolveWaterfallClientTimeoutMs } from '../../shared_libs/integration-contracts/waterfall/execution-policy.js';
@@ -172,6 +173,9 @@ function resolveToolExecuteTimeoutMs(
   input: Record<string, unknown>,
 ): number | undefined {
   const normalized = toolId.trim().toLowerCase();
+  if (normalized === 'opensosdata_business_lookup') {
+    return OPENSOSDATA_LOOKUP_CLIENT_TIMEOUT_MS;
+  }
   if (normalized === 'apify_run_actor_sync') {
     const requestedTimeoutMs = input.timeoutMs ?? APIFY_SYNC_DEFAULT_TIMEOUT_MS;
     if (

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

@@ -228,6 +228,8 @@ export 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;

package/dist/bundling-sources/shared_libs/integration-contracts/opensosdata/execution-policy.ts

@@ -0,0 +1,18 @@
+/** OpenSOSData's single-entity lookup can complete synchronously or poll a 202 job. */
+export const OPENSOSDATA_LOOKUP_REQUEST_TIMEOUT_MS = 120_000;
+export const OPENSOSDATA_POLL_INTERVAL_MS = 3_000;
+export const OPENSOSDATA_POLL_TIMEOUT_MS = 90_000;
+
+/**
+ * Preserve the provider's existing request and polling windows. A final poll
+ * can begin just before the poll window ends, so include that in-flight request
+ * as well as route/admission and response overhead. Explicit caller deadlines
+ * still take precedence; unrelated tools retain their existing budgets.
+ */
+export const OPENSOSDATA_LOOKUP_CLIENT_TIMEOUT_MS =
+  60_000 +
+  OPENSOSDATA_LOOKUP_REQUEST_TIMEOUT_MS +
+  OPENSOSDATA_POLL_TIMEOUT_MS +
+  OPENSOSDATA_POLL_INTERVAL_MS +
+  OPENSOSDATA_LOOKUP_REQUEST_TIMEOUT_MS +
+  15_000;

package/dist/bundling-sources/shared_libs/play-runtime/activity-observation.ts

@@ -263,10 +263,40 @@ function targetLabel(target: PlayActivityTarget): string {
     case 'step':
       return target.label ?? target.stepId;
     case 'capacity':
-      return target.label ?? `${target.pool} capacity`;
+      return target.pool === 'provider'
+        ? providerCapacityLabel(target.label)
+        : (target.label ?? `${target.pool} capacity`);
   }
 }
 
+/** Older waits carried a rate scope rather than a customer-facing provider. */
+export function providerCapacityLabel(label?: string): string {
+  if (!label) return 'The provider';
+  if (label.startsWith('org:')) return label.split(':')[1] || 'The provider';
+  return label.includes(':') ? 'The provider' : label;
+}
+
+function publicProviderCapacityObservation(
+  observation: PlayActivityObservation,
+): PlayActivityObservation {
+  if (
+    observation.target.kind !== 'capacity' ||
+    observation.target.pool !== 'provider'
+  )
+    return observation;
+  if (
+    !observation.target.label?.includes(':') &&
+    !observation.activityId.startsWith('capacity:provider:org:')
+  )
+    return observation;
+  const label = providerCapacityLabel(observation.target.label);
+  return {
+    ...observation,
+    activityId: `capacity:provider:${label}`,
+    target: { ...observation.target, label },
+  };
+}
+
 export function summarizePlayActivity(
   observation: PlayActivityObservation,
 ): string {
@@ -297,10 +327,10 @@ export function summarizePlayActivity(
       if (state.reason.kind === 'lease') {
         return `Contended: waiting for ${state.reason.resourceKind} lease ${state.reason.resourceLabel}.`;
       }
-      return `Paused: ${label}; the legacy producer did not report a typed reason.`;
+      return `Waiting: ${label}.`;
     case 'retrying':
       if (state.reason === 'rate_limit') {
-        return `Waiting for ${label} request capacity; the run will retry automatically.`;
+        return `Waiting for ${label}'s rate limit to allow more calls. Completed work is saved; remaining calls will continue automatically.`;
       }
       return `Delayed: ${label} will retry automatically.`;
     case 'scheduled':
@@ -385,6 +415,7 @@ export function projectPlayRunActivity(input: {
   status: string;
   updatedAt?: number | null;
   waitKind?: string | null;
+  waitBoundaryId?: string | null;
   waitUntil?: number | null;
   eventKey?: string | null;
   runtimeBackend?: string | null;
@@ -410,17 +441,24 @@ export function projectPlayRunActivity(input: {
   const latestExplicit = [...(input.explicit ?? [])]
     .filter((candidate) => !isTerminalActivityState(candidate.state))
     .sort((left, right) => right.observedAt - left.observedAt)[0];
-  // A provider wait is an observation, not a permanent run state. Once its
-  // deadline has passed, use the current lifecycle/step facts until the next
-  // producer observation arrives instead of claiming the old hold persists.
+  // Retry-After is the earliest retry, not evidence that execution resumed.
+  // Retain the reason while its provider boundary is still waiting, including
+  // lagging readers with no wait projection. A different durable wait wins.
+  const stillWaitingForProvider =
+    normalizedStatus === 'waiting' &&
+    (!input.waitKind ||
+      (input.waitKind === 'sleep' &&
+        input.waitBoundaryId?.includes(':provider-backpressure-') === true));
   const explicit =
+    !stillWaitingForProvider &&
     latestExplicit?.target.kind === 'capacity' &&
     latestExplicit.target.pool === 'provider' &&
     latestExplicit.state.kind === 'retrying' &&
     latestExplicit.state.retryAt < now
       ? null
       : latestExplicit;
-  if (explicit) return projection(explicit, now);
+  if (explicit)
+    return projection(publicProviderCapacityObservation(explicit), now);
 
   if (input.waitKind === 'detached_runner') {
     return projection(

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

@@ -57,6 +57,7 @@ import type {
 } from './governor/rate-state-backend';
 import type { MapRowOutcome } from './durability-store';
 import { stringifyPostgresJson } from './postgres-json';
+import { providerCapacityLabel } from './activity-observation';
 import { RUNTIME_ROW_OUTPUT_NOT_JSON_SERIALIZABLE } from './runtime-sheet-row-transition';
 import {
   RuntimeSheetRowWriter,
@@ -204,7 +205,7 @@ import {
   TOOL_EXECUTE_RUNNER_ACCEPTS_VALUE,
   TOOL_EXECUTE_PROVIDER_RATE_SCOPE_HEADER,
   TOOL_EXECUTE_PROVIDER_RATE_RETRY_SNAPSHOT_HEADER,
-  TOOL_EXECUTE_PROVIDER_THROTTLE_HEADER,
+  isAttestedProvider429Response,
   classifyToolExecuteHttpFailure,
   createToolExecuteHttpFailureAttemptTracker,
   parseToolExecuteRetryAfterMs,
@@ -9143,6 +9144,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
       successfulCount = Math.max(0, successfulCount - staleCompletedKeys.size);
       failedCount = Math.max(0, failedCount - staleFailedKeys.size);
+      this.#options.onMapRowsSettled?.({
+        playName: this.#options.playName,
+        runId: this.#options.runId,
+        tableNamespace: resolvedTableNamespace,
+        succeededRows: successfulCount,
+        failedRows: failedCount,
+      });
 
       // Isolated failures are a partial result only when at least one admitted
       // row completed. A fully failed admission run is systemic: preserve the
@@ -9995,6 +10003,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       });
     }
 
+    this.#options.onMapRowsSettled?.({
+      playName: this.#options.playName,
+      runId: this.#options.runId,
+      tableNamespace: resolvedTableNamespace,
+      succeededRows:
+        previouslyCompletedRowKeys.length + visibleCompletedRows.length,
+      failedRows: durableFailedRows,
+    });
+
     // This map's terminal rows have already crossed the persistence barrier
     // above. Keep that verified snapshot as the authored return value instead
     // of immediately re-reading the Runtime Sheet projection. A second read
@@ -14532,11 +14549,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     retryAtMs: number,
   ): void {
     const observedAt = Date.now();
+    const label = providerCapacityLabel(provider);
     this.emitExecutionEvent({
       type: 'activity.observed',
       observation: {
-        activityId: `capacity:provider:${provider}`,
-        target: { kind: 'capacity', pool: 'provider', label: provider },
+        activityId: `capacity:provider:${label}`,
+        target: { kind: 'capacity', pool: 'provider', label },
         state: {
           kind: 'retrying',
           reason: 'rate_limit',
@@ -19546,12 +19564,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                               : undefined;
                           }
                           if (
-                            dispatchedResponse.status === 429 &&
-                            dispatchedResponse.headers.get(
-                              TOOL_EXECUTE_PROVIDER_THROTTLE_HEADER,
-                            ) === '1'
+                            isAttestedProvider429Response(dispatchedResponse)
                           ) {
                             this.resourceGovernor.recordProvider429();
+                          }
+                          if (
+                            dispatchedResponse.status === 429 &&
+                            isAttestedProvider429Response(dispatchedResponse)
+                          ) {
                             provider429RetryDiagnosticStartedAt =
                               performance.now();
                             provider429RetryDiagnosticNextInvocationAttempt =

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

@@ -931,6 +931,14 @@ export interface ContextOptions {
      */
     supersededKeys?: string[];
   }>;
+  /** Distinct terminal rows after the map's persistence barrier, across resumes. */
+  onMapRowsSettled?: (input: {
+    playName?: string;
+    runId?: string;
+    tableNamespace: string;
+    succeededRows: number;
+    failedRows: number;
+  }) => void;
   /**
    * Persists coalesced, non-terminal row patches before a map suspends.
    * Terminal rows use onMapRowsCompleted; this narrow seam only preserves

package/dist/bundling-sources/shared_libs/play-runtime/run-snapshot-stream.ts

@@ -328,6 +328,7 @@ export function buildPlayRunStatusSnapshot(input: {
     status: projectedSnapshot.status,
     updatedAt: projectedSnapshot.updatedAt,
     waitKind: input.run.waitKind ?? input.run.wait?.kind ?? null,
+    waitBoundaryId: input.run.wait?.boundaryId ?? input.run.activeBoundaryId,
     waitUntil: input.run.waitUntil,
     eventKey: input.run.wait?.eventKey ?? null,
     runtimeBackend: input.run.runtimeBackend,

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/index.ts

@@ -496,6 +496,20 @@ export function runtimeSheetTerminalWriteCounts(input: {
   };
 }
 
+/** Distinct settled counts include saved siblings, never skipped input duplicates. */
+export function runtimeSheetTerminalMapCounts(
+  current: { persistedRows: number; succeededRows: number; failedRows: number },
+  map: { succeededRows: number; failedRows: number },
+): { persistedRows: number; succeededRows: number; failedRows: number } {
+  const succeededRows = Math.max(current.succeededRows, map.succeededRows);
+  const failedRows = Math.max(current.failedRows, map.failedRows);
+  return {
+    persistedRows: Math.max(current.persistedRows, succeededRows + failedRows),
+    succeededRows,
+    failedRows,
+  };
+}
+
 async function vercelBypassHeaders(
   config: PlayRunnerExecutionConfig,
 ): Promise<Record<string, string>> {
@@ -2308,6 +2322,35 @@ async function run(
       const MAP_ROW_UPDATED_EMIT_INTERVAL_MS = 200;
       const MAP_ROW_UPDATED_EMIT_SAMPLE_RATE = 100;
       return (event: PlayExecutionEvent) => {
+        if (event.type === 'map.suspended') {
+          const datasetId = createRuntimeDatasetId(
+            config.context.playName!,
+            event.artifactTableNamespace,
+          );
+          const settlement = runtimeMapDatasetSettlements.get(datasetId);
+          if (settlement) {
+            // This event follows the map writer's durability barrier. Only
+            // report accepted writes, not progress (which includes duplicates).
+            emitRunnerEvent(
+              {
+                type: 'execution_event',
+                event: {
+                  type: 'dataset.lifecycle',
+                  datasetId,
+                  path: settlement.path,
+                  tableNamespace: settlement.tableNamespace,
+                  phase: 'registered',
+                  persistedRows: settlement.persistedRows,
+                  succeededRows: settlement.succeededRows,
+                  failedRows: settlement.failedRows,
+                  complete: false,
+                  at: event.at,
+                },
+              },
+              options,
+            );
+          }
+        }
         if (event.type === 'map.row.updated') {
           mapRowUpdatedCount++;
           const now = Date.now();
@@ -2638,6 +2681,19 @@ async function run(
           ),
       });
     },
+    onMapRowsSettled: (input) => {
+      const datasetId = createRuntimeDatasetId(
+        input.playName ?? config.context.playName!,
+        input.tableNamespace,
+      );
+      const settlement = runtimeMapDatasetSettlements.get(datasetId);
+      if (settlement && (!input.runId || settlement.runId === input.runId)) {
+        Object.assign(
+          settlement,
+          runtimeSheetTerminalMapCounts(settlement, input),
+        );
+      }
+    },
     onMapRowsCompleted: async (input) => {
       // Persist executed rows (data + cell meta) into the tenant sheet —
       // the sheet is the source of truth for dataset state, and the

package/dist/bundling-sources/shared_libs/play-runtime/tool-execute-retry-policy.ts

@@ -86,6 +86,23 @@ export const TOOL_EXECUTE_PROVIDER_THROTTLE_HEADER =
   'x-deepline-provider-throttle';
 export const TOOL_EXECUTE_PROVIDER_PACING_WAIT_CODE = 'PROVIDER_PACING_WAIT';
 
+/** A trusted provider 429 remains observable if the gateway cannot commit its body. */
+export function isAttestedProvider429Response(response: {
+  status: number;
+  headers: Pick<Headers, 'get'>;
+}): boolean {
+  if (response.headers.get(TOOL_EXECUTE_PROVIDER_THROTTLE_HEADER) !== '1') {
+    return false;
+  }
+  if (response.status === 429) return true;
+  const code = response.headers.get('x-deepline-error-code');
+  return (
+    response.status === 409 &&
+    (code === 'durable_invocation_outcome_unknown' ||
+      code === 'durable_invocation_commit_failed')
+  );
+}
+
 /**
  * Parse the advertisement as a comma-separated token list so a later runner can
  * add a capability without a second header. An absent or unparsable value means