deepline 0.3.409 → 0.3.410

package/dist/bundling-sources/sdk/src/runs/read-errors.ts

@@ -1,6 +1,14 @@
 import { DeeplineError } from '../errors';
 
 export function isTransientPlayRunReadError(error: unknown): boolean {
+  // The HTTP failure is diagnostic; an unconfirmed admission has no identity
+  // that makes repeating it safe, even when its response was a 5xx.
+  if (
+    error instanceof DeeplineError &&
+    error.code === 'PLAY_START_OUTCOME_UNKNOWN'
+  ) {
+    return false;
+  }
   if (
     error instanceof DeeplineError &&
     error.code === 'PLAY_STREAM_NETWORK_ABORTED'

package/dist/bundling-sources/sdk/src/runs/watch-polling.ts

@@ -9,21 +9,37 @@ import {
 } from '../../../shared_libs/play-runtime/run-snapshot-stream.js';
 import { isTransientPlayRunReadError } from './read-errors';
 
-/** The watch endpoint is a small authenticated REST read, polled every two seconds. */
+/** Steady-state cadence for the small authenticated REST snapshot. */
 export const RUN_WATCH_POLL_INTERVAL_MS = 2_000;
+const RUN_WATCH_STARTUP_POLL_INTERVAL_MS = 500;
+const RUN_WATCH_STARTUP_WINDOW_MS = 6_000;
 
 type WatchHttp = {
   get<T = unknown>(
     path: string,
-    options?: { signal?: AbortSignal },
+    options?: {
+      signal?: AbortSignal;
+      onResponse?: (response: Response) => void;
+    },
   ): Promise<T>;
 };
 
+export type WatchPollObservation = {
+  poll: number;
+  durationMs: number;
+  status?: number;
+  serverTiming?: string;
+};
+
 export type WatchRunEventsOptions = {
   http: WatchHttp;
   runId: string;
   signal?: AbortSignal;
-  /** @internal Test seam; production callers use the fixed two-second cadence. */
+  /** Defer log-store reads until the run is terminal; the final log tail is unchanged. */
+  deferLogs?: boolean;
+  /** Skip log-store reads entirely for consumers that never render run logs. */
+  omitTerminalLogs?: boolean;
+  /** @internal Test seam; overrides the entire adaptive cadence. */
   pollIntervalMs?: number;
   onNotice?: (message: string) => void;
   onRetry?: (info: {
@@ -31,11 +47,24 @@ export type WatchRunEventsOptions = {
     delayMs: number;
     reason: string;
   }) => void;
+  /** @internal Exposes bounded request timing for CLI diagnostics. */
+  onPoll?: (observation: WatchPollObservation) => void;
+  /** @internal Request the existing status response on the terminal poll. */
+  terminalStatus?: {
+    full?: boolean;
+    billing?: boolean;
+    runStatus?: boolean;
+    onStatus: (
+      response: Record<string, unknown>,
+      status: string,
+    ) => void | Promise<void>;
+  };
 };
 
 type WatchSnapshotResponse = {
   runId: string;
   snapshot: PlayRunLiveSnapshot;
+  terminalStatus?: Record<string, unknown>;
 };
 
 type WatchRunLogPage = {
@@ -83,7 +112,24 @@ function readSnapshotResponse(
   ) {
     throw new Error(`Run watch returned an invalid snapshot for ${runId}.`);
   }
-  return { runId, snapshot: snapshot as PlayRunLiveSnapshot };
+  if (
+    record.terminalStatus !== undefined &&
+    (!record.terminalStatus ||
+      typeof record.terminalStatus !== 'object' ||
+      Array.isArray(record.terminalStatus) ||
+      !isTerminalPlayRunLiveStatus((snapshot as PlayRunLiveSnapshot).status))
+  ) {
+    throw new Error(
+      `Run watch returned an invalid terminal status for ${runId}.`,
+    );
+  }
+  return {
+    runId,
+    snapshot: snapshot as PlayRunLiveSnapshot,
+    ...(record.terminalStatus !== undefined
+      ? { terminalStatus: record.terminalStatus as Record<string, unknown> }
+      : {}),
+  };
 }
 
 async function backfillRotatedLogTail(input: {
@@ -141,26 +187,85 @@ export async function* watchRunEvents(
   options: WatchRunEventsOptions,
 ): AsyncGenerator<PlayRunStreamEvent> {
   const { http, runId, signal } = options;
-  const path = `/api/v2/runs/${encodeURIComponent(runId)}?watchSnapshot=true`;
+  const params = new URLSearchParams({ watchSnapshot: 'true' });
+  if (options.deferLogs) params.set('deferLogs', 'true');
+  if (options.omitTerminalLogs) params.set('omitTerminalLogs', 'true');
+  if (options.terminalStatus) {
+    params.set(
+      'terminalStatus',
+      options.terminalStatus.full ? 'full' : 'compact',
+    );
+    if (options.terminalStatus.billing === false)
+      params.set('billing', 'false');
+    if (options.terminalStatus.runStatus)
+      params.set('terminalRunStatus', 'true');
+  }
+  const path = `/api/v2/runs/${encodeURIComponent(runId)}?${params}`;
   const streamId = `play-run-watch:${runId}`;
-  const pollIntervalMs = options.pollIntervalMs ?? RUN_WATCH_POLL_INTERVAL_MS;
+  const watchStartedAt = Date.now();
   let previous: PlayRunStreamDiffState = EMPTY_PLAY_RUN_STREAM_DIFF_STATE;
   let consecutiveFailures = 0;
   let outageNoticeSent = false;
+  let pollCount = 0;
 
   while (!signal?.aborted) {
     const pollStartedAt = Date.now();
+    const poll = ++pollCount;
+    // Keep a moderate cadence through the sandbox startup window. This halves
+    // short-run snapshot reads while avoiding a two-second detection gap just
+    // after Daytona finishes starting a fresh sandbox.
+    const pollIntervalMs =
+      options.pollIntervalMs ??
+      (pollStartedAt - watchStartedAt < RUN_WATCH_STARTUP_WINDOW_MS
+        ? RUN_WATCH_STARTUP_POLL_INTERVAL_MS
+        : RUN_WATCH_POLL_INTERVAL_MS);
     let snapshot: PlayRunLiveSnapshot;
+    let terminalStatus: Record<string, unknown> | undefined;
+    let responseStatus: number | undefined;
+    let serverTiming: string | undefined;
+    let pollReported = false;
+    const reportPoll = () => {
+      if (!options.onPoll || pollReported) return;
+      pollReported = true;
+      try {
+        options.onPoll({
+          poll,
+          durationMs: Date.now() - pollStartedAt,
+          ...(responseStatus !== undefined ? { status: responseStatus } : {}),
+          ...(serverTiming ? { serverTiming } : {}),
+        });
+      } catch {
+        // Diagnostics must not turn a successful poll into a retry.
+      }
+    };
     try {
-      const response = await http.get<unknown>(path, { signal });
-      snapshot = await backfillRotatedLogTail({
-        http,
-        runId,
-        snapshot: readSnapshotResponse(response, runId).snapshot,
-        previous,
+      const response = await http.get<unknown>(path, {
         signal,
+        ...(options.onPoll
+          ? {
+              onResponse: (response: Response) => {
+                responseStatus = response.status;
+                serverTiming =
+                  response.headers.get('server-timing') ?? undefined;
+              },
+            }
+          : {}),
       });
+      const parsed = readSnapshotResponse(response, runId);
+      terminalStatus = parsed.terminalStatus;
+      // Deferred watchers need the terminal tail, not a replay of every skipped log.
+      snapshot = options.deferLogs
+        ? parsed.snapshot
+        : await backfillRotatedLogTail({
+            http,
+            runId,
+            snapshot: parsed.snapshot,
+            previous,
+            signal,
+          });
+      reportPoll();
     } catch (error) {
+      reportPoll();
       if (signal?.aborted) {
         return;
       }
@@ -176,7 +281,7 @@ export async function* watchRunEvents(
           reason,
         });
         options.onNotice?.(
-          `[watch] run snapshot request failed; retrying every ${pollIntervalMs / 1_000}s (${reason})`,
+          `[watch] run snapshot request failed; retrying snapshot polling (${reason})`,
         );
         outageNoticeSent = true;
       }
@@ -196,6 +301,12 @@ export async function* watchRunEvents(
     }
     consecutiveFailures = 0;
 
+    // Give the consumer the same durable status it would otherwise fetch
+    // before emitting terminal events that cause that serial HTTP request.
+    if (terminalStatus) {
+      await options.terminalStatus?.onStatus(terminalStatus, snapshot.status);
+    }
+
     const diff = diffPlayRunStreamEvents({
       streamId,
       snapshot,

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

@@ -1,5 +1,9 @@
 import { resolveLookupClientTimeoutMs } from '../../shared_libs/integration-contracts/lookup-execution-policy.js';
 import type { ToolResultBilling } from '../../shared_libs/plays/tool-result-types.js';
+import {
+  parseExecuteServerTiming,
+  type ExecuteServerTiming,
+} from '../../shared_libs/play-runtime/execute-server-timing';
 import { resolveTheirstackClientTimeoutMs } from '../../shared_libs/integration-contracts/theirstack/execution-policy.js';
 import { resolveWaterfallClientTimeoutMs } from '../../shared_libs/integration-contracts/waterfall/execution-policy.js';
 import {
@@ -19,6 +23,7 @@ import {
 import { DeeplineError, ToolExecutionError } from './errors';
 import type { HttpClient } from './http';
 import { validateCliInvocationId } from './cli-invocation-id';
+import { ATOMIC_TOOL_EXECUTE_SUPPORTED_HEADER } from '../../shared_libs/integration-contracts/execute-retry-contract.js';
 
 const INCLUDE_TOOL_METADATA_HEADER = 'x-deepline-include-tool-metadata';
 const EXECUTE_RESPONSE_CONTRACT_HEADER = 'x-deepline-execute-response-contract';
@@ -117,6 +122,8 @@ const DEEPLINEAGENT_EXECUTE_TIMEOUT_MS = 15 * 60 * 1000;
 
 export type ExecuteToolRawOptions = {
   includeToolMetadata?: boolean;
+  /** Use the atomic-tools endpoint, which rejects Plays before charge admission. */
+  atomicToolOnly?: boolean;
   responseIntent?: 'dataset' | 'raw' | 'row_artifact';
   metadata?: Record<string, unknown>;
   timeout?: number;
@@ -140,7 +147,9 @@ export type ExecuteToolRawOptions = {
     receivedAtMs: number;
     httpStatus: number;
     state: 'completed' | 'failed' | 'cancelled';
-  }) => void;
+  }) => void | Promise<void>;
+  /** Optional response-path diagnostics; does not affect execution or retries. */
+  onServerTiming?: (timing: ExecuteServerTiming | null) => void | Promise<void>;
 };
 
 /** Durable state returned for a keyed tool execution. */
@@ -376,13 +385,6 @@ export class ToolCalls {
         inputSnapshot,
         this.configuredRequestTimeoutMs,
       );
-    if (idempotencyKey !== undefined) {
-      await this.lookupExecutionByKey(
-        idempotencyKey,
-        timeoutMs,
-        options?.cliInvocationId,
-      );
-    }
     const isApifySync = toolId.trim().toLowerCase() === 'apify_run_actor_sync';
     const headers = {
       [EXECUTE_RESPONSE_CONTRACT_HEADER]: RAW_V2_EXECUTE_RESPONSE_CONTRACT,
@@ -436,18 +438,35 @@ export class ToolCalls {
             : failure
               ? 'failed'
               : null;
-      if (terminal)
-        options?.onResponseReceived?.({
+      if (!terminal || !options?.onResponseReceived) return;
+      const reportObservationFailure = () =>
+        console.error('[tools.execute] response observation failed');
+      try {
+        const notification = options.onResponseReceived({
           receivedAtMs: lastResponse.receivedAtMs,
           httpStatus: lastResponse.httpStatus,
           state: terminal,
         });
+        void Promise.resolve(notification).catch(reportObservationFailure);
+      } catch {
+        reportObservationFailure();
+      }
     };
-    const request = async (requestTimeoutMs: number | undefined) => {
-      lastResponse = null;
-      try {
-        return await this.http.post<ToolExecution<TData, TMeta>>(
-          `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
+    const legacyEndpoint = `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`;
+    let useLegacyEndpoint = idempotencyKey === undefined;
+    const atomicToolOnly = options?.atomicToolOnly === true;
+    const dispatchRequest = async (
+      requestTimeoutMs: number | undefined,
+    ): Promise<ToolExecution<TData, TMeta>> => {
+      let recoverySupported = false;
+      let atomicToolsSupported = false;
+      const post = () =>
+        this.http.post<ToolExecution<TData, TMeta>>(
+          atomicToolOnly
+            ? `/api/v2/tools/${encodeURIComponent(toolId)}/execute`
+            : useLegacyEndpoint
+              ? legacyEndpoint
+              : `/api/v2/executions/by-key/${encodeURIComponent(idempotencyKey!)}?tool_id=${encodeURIComponent(toolId)}`,
           {
             payload: inputSnapshot,
             ...(metadataSnapshot ? { metadata: metadataSnapshot } : {}),
@@ -456,21 +475,91 @@ export class ToolCalls {
           {
             timeout: requestTimeoutMs,
             maxRetries: idempotencyKey ? 0 : (options?.maxRetries ?? 0),
-            retryApiErrors: options?.retryApiErrors === true,
+            ...(atomicToolOnly &&
+            !idempotencyKey &&
+            options?.maxRetries === undefined
+              ? { executePolicyMaxRetries: 2 }
+              : {}),
+            retryApiErrors: atomicToolOnly || options?.retryApiErrors === true,
+            retryFromExecutePolicy: atomicToolOnly,
             exactUrlOnly: true,
             toolId,
             idempotencyKey,
-            onResponse: () => {
+            onResponse: (response) => {
               lastResponse = null;
+              atomicToolsSupported =
+                response.headers.get(ATOMIC_TOOL_EXECUTE_SUPPORTED_HEADER) ===
+                'true';
+              recoverySupported =
+                response.headers.get('X-Deepline-Idempotency-Supported') ===
+                'true';
+              if (options?.onServerTiming) {
+                try {
+                  const notification = options.onServerTiming(
+                    parseExecuteServerTiming(
+                      response.headers.get('server-timing'),
+                    ),
+                  );
+                  void Promise.resolve(notification).catch(() => undefined);
+                } catch {
+                  // Diagnostic callbacks cannot turn a delivered mutation into
+                  // an ambiguous failure or trigger execution recovery.
+                }
+              }
             },
             onResponseBody: (observation) => {
               lastResponse = observation;
             },
           },
         );
+      try {
+        return await post();
+      } catch (error) {
+        if (atomicToolOnly) {
+          if (
+            !atomicToolsSupported &&
+            !recoverySupported &&
+            !(error instanceof ToolExecutionError) &&
+            error instanceof DeeplineError &&
+            (error.statusCode === 404 || error.statusCode === 405)
+          ) {
+            throw new DeeplineError(
+              'This server does not support atomic tool execution.',
+              error.statusCode,
+              'ATOMIC_TOOL_EXECUTE_UNSUPPORTED',
+            );
+          }
+          throw error;
+        }
+        // Older servers reject this named action before dispatch. Confirm their
+        // legacy recovery contract before sending a mutating request there.
+        // Supported tool failures, ambiguous delivery, and auth errors never
+        // trigger this fallback.
+        if (
+          useLegacyEndpoint ||
+          recoverySupported ||
+          !(error instanceof DeeplineError) ||
+          (error.statusCode !== 404 && error.statusCode !== 405)
+        )
+          throw error;
+        lastResponse = null;
+        await this.lookupExecutionByKey(
+          idempotencyKey!,
+          requestTimeoutMs,
+          options?.cliInvocationId,
+        );
+        useLegacyEndpoint = true;
+        return post();
+      }
+    };
+    const request = async (
+      requestTimeoutMs: number | undefined,
+    ): Promise<ToolExecution<TData, TMeta>> => {
+      lastResponse = null;
+      try {
+        return await dispatchRequest(requestTimeoutMs);
       } catch (error) {
-        // Only the final HTTP rejection, not an intermediate retry or an
-        // ambiguous network/cancellation failure, proves a response endpoint.
+        // Observe only the final rejection, after compatibility dispatch.
         observeTerminal({ error });
         throw error;
       }

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

@@ -219,6 +219,18 @@ export interface ProviderDefinition {
  */
 export type { DeeplineToolCategory };
 
+/** Visible category membership count; a tool can belong to several categories. */
+export interface ToolCategorySummary {
+  name: string;
+  count: number;
+}
+
+/** Selected tool definitions and all visible category counts. */
+export interface ToolCategoryListing {
+  categories: ToolCategorySummary[];
+  tools: ToolDefinition[];
+}
+
 /**
  * Summary definition of a callable provider-backed tool.
  *
@@ -877,6 +889,8 @@ export interface PlayRunPackage {
   warnings?: string[];
   /** Step-level summaries emitted by the runtime. */
   steps: Array<Record<string, unknown>>;
+  /** Whether the admitted graph or observed ledger expects public steps. */
+  stepsExpected?: boolean;
   /** Named output summaries, including dataset handles and scalar outputs. */
   outputs: Record<string, Record<string, unknown>>;
   /** Every durable Dataset Handle explicitly registered by this run. */
@@ -1854,6 +1868,8 @@ export interface PlayRunStart {
   dashboardUrl?: string;
   /** Terminal status returned when the start request used a short completion wait. */
   finalStatus?: unknown;
+  /** Explicit full representation assembled by the canonical status reader. */
+  finalStatusView?: 'full';
   /** Canonical compact run package returned by current SDK/API responses. */
   package?: PlayRunPackage;
 }
@@ -2178,6 +2194,8 @@ export interface StartPlayRunRequest {
   maxCredits?: number;
   /** Optionally let the start request wait briefly and return a terminal result. */
   waitForCompletionMs?: number;
+  /** Request full terminal status within an optional start completion wait. */
+  terminalStatus?: 'full';
   /**
    * Per-run execution profile override. The server defaults to absurd. The
    * Only `absurd` is accepted; most callers should leave this unset.

package/dist/bundling-sources/shared_libs/integration-contracts/execute-retry-contract.ts

@@ -0,0 +1,37 @@
+/**
+ * Trusted app-to-execution-gateway contract for replaying a completed
+ * integration attempt. The app resolves provider policy while it has the
+ * executable integration catalog loaded; the gateway persists this value with
+ * the exact response bytes and never loads provider code itself.
+ */
+export const EXECUTE_RETRY_POLICY_HEADER = 'x-deepline-execute-retry-policy';
+
+export const EXECUTE_RETRY_POLICY_VERSION = 1;
+
+export type ExecuteRetryPolicy =
+  | 'transient-http-safe'
+  | 'transient-http-unsafe';
+
+export function serializeExecuteRetryPolicy(
+  retrySafeTransientHttp: boolean,
+): string {
+  return `v${EXECUTE_RETRY_POLICY_VERSION}:${
+    retrySafeTransientHttp ? 'transient-http-safe' : 'transient-http-unsafe'
+  }`;
+}
+
+export function parseExecuteRetryPolicy(
+  value: string | null | undefined,
+): ExecuteRetryPolicy | null {
+  if (value === `v${EXECUTE_RETRY_POLICY_VERSION}:transient-http-safe`) {
+    return 'transient-http-safe';
+  }
+  if (value === `v${EXECUTE_RETRY_POLICY_VERSION}:transient-http-unsafe`) {
+    return 'transient-http-unsafe';
+  }
+  return null;
+}
+
+/** Marks authoritative responses from the atomic-tools execution endpoint. */
+export const ATOMIC_TOOL_EXECUTE_SUPPORTED_HEADER =
+  'x-deepline-atomic-tool-supported';

package/dist/bundling-sources/shared_libs/integration-contracts/package.json

@@ -0,0 +1,3 @@
+{
+  "sideEffects": false
+}

package/dist/bundling-sources/shared_libs/play-data-plane/r2.ts

@@ -193,7 +193,7 @@ export async function uploadBufferToR2(input: {
   logR2Perf('client', input.key, clientStartedAt, { kind: bucketKind });
 
   const sendStartedAt = Date.now();
-  await client.send(
+  const result = await client.send(
     new PutObjectCommand({
       Bucket: config.bucket,
       Key: input.key,
@@ -203,6 +203,8 @@ export async function uploadBufferToR2(input: {
     }),
   );
   logR2Perf('put-send', input.key, sendStartedAt, {
+    attempts: result.$metadata.attempts ?? null,
+    retryDelayMs: result.$metadata.totalRetryDelay ?? null,
     kind: bucketKind,
     bytes: input.body.byteLength,
   });