executions.ts

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../resource';
import { isRequestOptions } from '../../core';
import { APIPromise } from '../../core';
import * as Core from '../../core';
import * as DevboxesAPI from './devboxes';
import {
  LongPollRequestOptions,
  longPollUntil,
  resolveLongPollTimeoutMs,
} from '@runloop/api-client/lib/polling';
import { Stream } from '../../streaming';
import { withStreamAutoReconnect } from '@runloop/api-client/lib/streaming-reconnection';

export class Executions extends APIResource {
  /**
   * Get the latest status of a previously launched asynchronous execuction including
   * stdout/error and the exit code if complete.
   */
  retrieve(
    devboxId: string,
    executionId: string,
    query?: ExecutionRetrieveParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxesAPI.DevboxAsyncExecutionDetailView>;
  retrieve(
    devboxId: string,
    executionId: string,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxesAPI.DevboxAsyncExecutionDetailView>;
  retrieve(
    devboxId: string,
    executionId: string,
    query: ExecutionRetrieveParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxesAPI.DevboxAsyncExecutionDetailView> {
    if (isRequestOptions(query)) {
      return this.retrieve(devboxId, executionId, {}, query);
    }
    return this._client.get(`/v1/devboxes/${devboxId}/executions/${executionId}`, { query, ...options });
  }

  /**
   * Execute the given command in the Devbox shell asynchronously and returns the
   * execution that can be used to track the command's progress.
   */
  executeAsync(
    id: string,
    body: ExecutionExecuteAsyncParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxesAPI.DevboxAsyncExecutionDetailView> {
    return this._client.post(`/v1/devboxes/${id}/execute_async`, { body, ...options });
  }

  /**
   * Wait for an async execution to complete.
   * Long Polls the execution status until it reaches completed state.
   *
   * @param id - Devbox ID
   * @param executionId - Execution ID
   * @param options - request options with optional long-poll configuration.
   */
  async awaitCompleted(
    id: string,
    executionId: string,
    options?: LongPollRequestOptions<DevboxesAPI.DevboxAsyncExecutionDetailView>,
  ): Promise<DevboxesAPI.DevboxAsyncExecutionDetailView> {
    return longPollUntil(
      (signal) =>
        this._client.post(`/v1/devboxes/${id}/executions/${executionId}/wait_for_status`, {
          body: { statuses: ['completed'] },
          signal,
          // Per-request HTTP timeout must exceed the server's max long-poll hold (25s)
          // so the server's 408 always arrives before the client aborts the connection.
          // The longPollUntil AbortSignal enforces the caller's actual deadline.
          timeout: 600000,
          // Disable base-client retries so 408s surface immediately to longPollUntil
          // (the server's wait_for_status endpoint sets x-should-retry: true for executions).
          maxRetries: 0,
        }),
      {
        timeoutMs: resolveLongPollTimeoutMs(options),
        shouldStop: (result) => result.status === 'completed',
        signal: options?.signal,
      },
    );
  }

  /**
   * Execute a bash command in the Devbox shell, await the command completion and
   * return the output. Note: attach_stdin parameter is not supported for synchronous
   * execution.
   *
   * @deprecated
   */
  executeSync(
    id: string,
    body: ExecutionExecuteSyncParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxesAPI.DevboxExecutionDetailView> {
    return this._client.post(`/v1/devboxes/${id}/execute_sync`, {
      body,
      timeout: this._client.timeout ?? 600000,
      ...options,
    });
  }

  /**
   * Kill a previously launched asynchronous execution if it is still running by
   * killing the launched process. Optionally kill the entire process group.
   */
  kill(
    devboxId: string,
    executionId: string,
    body?: ExecutionKillParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxesAPI.DevboxAsyncExecutionDetailView>;
  kill(
    devboxId: string,
    executionId: string,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxesAPI.DevboxAsyncExecutionDetailView>;
  kill(
    devboxId: string,
    executionId: string,
    body: ExecutionKillParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxesAPI.DevboxAsyncExecutionDetailView> {
    if (isRequestOptions(body)) {
      return this.kill(devboxId, executionId, {}, body);
    }
    return this._client.post(`/v1/devboxes/${devboxId}/executions/${executionId}/kill`, { body, ...options });
  }

  /**
   * Send nonempty text or a signal to an execution started with attach_stdin
   * enabled. The request body is required. Supply exactly one of nonempty text or a
   * non-null signal. Wait for each send before sending more input or EOF; concurrent
   * requests are not ordered and retries after connection failures can replay input.
   */
  sendStdIn(
    devboxId: string,
    executionId: string,
    body: ExecutionSendStdInParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxesAPI.DevboxSendStdInResult> {
    return this._client.post(`/v1/devboxes/${devboxId}/executions/${executionId}/send_std_in`, {
      body,
      ...options,
    });
  }

  /**
   * Tails the stderr logs for the given execution with SSE streaming
   */
  streamStderrUpdates(
    devboxId: string,
    executionId: string,
    query: ExecutionStreamStderrUpdatesParams | undefined = {},
    options?: Core.RequestOptions,
  ): APIPromise<Stream<ExecutionUpdateChunk>> {
    const defaultHeaders = {
      Accept: 'text/event-stream',
    };
    const mergedOptions: Core.RequestOptions = {
      headers: defaultHeaders,
      ...options,
    };
    const parsedInitialOffset =
      query.offset !== undefined && query.offset !== '' && !Number.isNaN(Number(query.offset)) ?
        Number(query.offset)
      : undefined;
    const getStream: (offset: number | undefined) => APIPromise<Stream<ExecutionUpdateChunk>> = (offset) => {
      const n = offset ?? parsedInitialOffset ?? 0;
      return this._client.get(`/v1/devboxes/${devboxId}/executions/${executionId}/stream_stderr_updates`, {
        query: { ...query, offset: String(n) },
        ...mergedOptions,
        stream: true,
      });
    };
    return withStreamAutoReconnect(getStream, (item) => item.offset);
  }

  /**
   * Tails the stdout logs for the given execution with SSE streaming
   */
  streamStdoutUpdates(
    devboxId: string,
    executionId: string,
    query: ExecutionStreamStdoutUpdatesParams | undefined = {},
    options?: Core.RequestOptions,
  ): APIPromise<Stream<ExecutionUpdateChunk>> {
    const defaultHeaders = {
      Accept: 'text/event-stream',
    };
    const mergedOptions: Core.RequestOptions = {
      headers: defaultHeaders,
      ...options,
    };
    const parsedInitialOffset =
      query.offset !== undefined && query.offset !== '' && !Number.isNaN(Number(query.offset)) ?
        Number(query.offset)
      : undefined;
    const getStream: (offset: number | undefined) => APIPromise<Stream<ExecutionUpdateChunk>> = (offset) => {
      const n = offset ?? parsedInitialOffset ?? 0;
      return this._client.get(`/v1/devboxes/${devboxId}/executions/${executionId}/stream_stdout_updates`, {
        query: { ...query, offset: String(n) },
        ...mergedOptions,
        stream: true,
      });
    };
    return withStreamAutoReconnect(getStream, (item) => item.offset);
  }
}

export interface ExecutionUpdateChunk {
  /**
   * The latest log stream chunk.
   */
  output: string;

  /**
   * The byte offset of this chunk of log stream.
   */
  offset?: number;
}

export interface ExecutionRetrieveParams {
  /**
   * Last n lines of standard error / standard out to return (default: 100)
   */
  last_n?: string;
}

export interface ExecutionExecuteAsyncParams {
  /**
   * The command to execute via the Devbox shell. Commands are run from the user home
   * directory in a fresh login shell.
   */
  command: string;

  /**
   * Whether to attach stdin streaming for async commands. Not valid for execute_sync
   * endpoint. Defaults to false if not specified.
   */
  attach_stdin?: boolean | null;
}

export interface ExecutionExecuteSyncParams {
  /**
   * The command to execute via the Devbox shell. Commands are run from the user home
   * directory in a fresh login shell.
   */
  command: string;

  /**
   * Whether to attach stdin streaming for async commands. Not valid for execute_sync
   * endpoint. Defaults to false if not specified.
   */
  attach_stdin?: boolean | null;
}

export interface ExecutionKillParams {
  /**
   * Whether to kill the entire process group (default: false). If true, kills all
   * processes in the same process group as the target process.
   */
  kill_process_group?: boolean | null;
}

export interface ExecutionSendStdInParams {
  /**
   * Signal to send to std in of the running execution.
   */
  signal?: 'EOF' | 'INTERRUPT' | null;

  /**
   * Text to send to std in of the running execution.
   */
  text?: string | null;
}

export interface ExecutionStreamStderrUpdatesParams {
  /**
   * The byte offset to start the stream from (if unspecified, starts from the
   * beginning of the stream)
   */
  offset?: string;
}

export interface ExecutionStreamStdoutUpdatesParams {
  /**
   * The byte offset to start the stream from (if unspecified, starts from the
   * beginning of the stream)
   */
  offset?: string;
}

export declare namespace Executions {
  export {
    type ExecutionUpdateChunk as ExecutionUpdateChunk,
    type ExecutionRetrieveParams as ExecutionRetrieveParams,
    type ExecutionExecuteAsyncParams as ExecutionExecuteAsyncParams,
    type ExecutionExecuteSyncParams as ExecutionExecuteSyncParams,
    type ExecutionKillParams as ExecutionKillParams,
    type ExecutionSendStdInParams as ExecutionSendStdInParams,
    type ExecutionStreamStderrUpdatesParams as ExecutionStreamStderrUpdatesParams,
    type ExecutionStreamStdoutUpdatesParams as ExecutionStreamStdoutUpdatesParams,
  };
}