upload method for stagehand #1037

udaybuilds47 · 2025-08-28T16:20:33Z

stagehand upload method

why

stagehand could click, type, scrape… but uploads were messy.
no way to handle hidden inputs, chooser popups, urls, buffers.
no natural language → file input.
no clean support across local + browserbase.
so i built it.

what changed

1. new types

export type FileSpec = 
  | string 
  | { path: string }
  | { name: string; mimeType: string; buffer: Buffer };

export interface UploadResult {
  success: boolean;
  method: "input" | "chooser" | "fallback";
  hint: string;
  selector?: string;
  fileName?: string;
  message: string;
}

export interface HistoryEntry {
  method: "act" | "extract" | "observe" | "navigate" | "upload";
  // …
}

2. new api

await stagehand.upload("Upload resume", fileSpec)

ai finds the right element (observe)
tries 3 ways: input → chooser → fallback
works with urls, paths, or raw buffers
runs in local + browserbase the same way
returns structured UploadResult

3. file processing

fetches urls → buffer in memory
figures out mime + name
supports direct buffers
no temp files, all in memory

4. integration

history logs upload events
ready for metrics
typed & safe

test plan

✅ done

pdf upload from url
ai finds correct input
submit works after upload
tested on local + browserbase
url / buffer / local path support
observe handles iframes/shadow dom

🧪 next

multiple file inputs
hidden + chooser flows
iframes + dynamic forms
large files + different mime types
failure modes (bad url, network, limits, perms)

notes

pure ai, no hardcoded selectors
modular → easy to extend
efficient: single dom query, direct memory stream
safe: no file writes, validates urls, respects mime

usage

await stagehand.upload("Upload this file", "https://example.com/file.pdf");

await stagehand.upload("Upload resume", resumeUrl);
await stagehand.upload("Upload cover letter", letterUrl);

await stagehand.upload("Upload doc", {
  name: "document.pdf",
  mimeType: "application/pdf",
  buffer: pdfBuffer
});

impact

stagehand now does uploads properly.
handles messy real-world forms.
natural language → correct element.
works across environments.
less brittle, more useful.
opens up workflows like automated form filling + doc processing.

basically: it can now upload files.

p.s. also my first oss contribution

- Removed the file download function from the upload example, simplifying the process by allowing direct URL uploads. - Integrated dotenv for environment variable management. - Updated the upload method to handle URLs directly, downloading files as needed. - Improved error messages for better debugging and user feedback. - Adjusted logging to provide clearer insights into the upload process.

- Set the environment to "BROWSERBASE" in the Stagehand initialization. - Enhanced debugging by adding console logs for element evaluation in the file input check.

changeset-bot · 2025-08-28T16:20:37Z

🦋 Changeset detected

Latest commit: bce40bc

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

greptile-apps

Greptile Summary

This PR introduces file upload functionality to Stagehand, addressing a significant capability gap in the web automation library. The implementation adds a new upload() method that accepts natural language instructions to locate file inputs and supports multiple file sources including URLs, local file paths, and in-memory buffers.

The core architecture employs a three-tier fallback strategy: first attempting direct file input detection, then triggering file choosers, and finally using heuristic search to find associated upload controls. The method leverages Stagehand's existing observe() functionality for AI-powered element detection, ensuring it works with complex scenarios like hidden inputs, iframes, and shadow DOM elements.

Key additions include new TypeScript types (FileSpec and UploadResult) that provide flexible file specification options and structured feedback about upload operations. The implementation handles URL fetching with automatic MIME type detection, processes files entirely in memory without temporary files, and maintains consistent behavior across both local and Browserbase environments.

The upload method integrates seamlessly with Stagehand's existing history tracking system, logging upload events for observability. An example test file demonstrates the intended usage pattern: providing natural language hints to identify upload elements, followed by standard form interactions.

Confidence score: 3/5

This PR introduces complex new functionality with multiple execution paths that could fail in various edge cases
Score reflects concerns about package.json changes that could break build processes and potential type definition issues in FileSpec
Pay close attention to lib/package.json build configuration changes and types/stagehand.ts FileSpec type definition

_{4 files reviewed, 4 comments}

_{Edit Code Review Bot Settings | Greptile}

greptile-apps · 2025-08-28T16:21:11Z

types/stagehand.ts

+export type FileSpec =
+  | string
+  | {
+      /** Absolute path on disk to the file. */
+      path?: string;
+      /** Name to use for the file (required if using buffer). */
+      name?: string;
+      /** MIME type for the file (required if using buffer). */
+      mimeType?: string;
+      /** Raw file bytes (requires name + mimeType). */
+      buffer?: Buffer;
+    };


logic: FileSpec type allows invalid combinations like { name: 'file.txt' } without buffer or path. Consider using discriminated unions to enforce valid combinations.

Suggested change

export type FileSpec =

| string

| {

/** Absolute path on disk to the file. */

path?: string;

/** Name to use for the file (required if using buffer). */

name?: string;

/** MIME type for the file (required if using buffer). */

mimeType?: string;

/** Raw file bytes (requires name + mimeType). */

buffer?: Buffer;

};

export type FileSpec =

| string

| {

/** Absolute path on disk to the file. */

path: string;

}

| {

/** Name to use for the file (required if using buffer). */

name: string;

/** MIME type for the file (required if using buffer). */

mimeType: string;

/** Raw file bytes (requires name + mimeType). */

buffer: Buffer;

};

greptile-apps · 2025-08-28T16:21:21Z

lib/index.ts

+            (el): boolean => {
+              const tagName = el.tagName.toLowerCase();
+              const type = (el as HTMLInputElement).type;
+              console.log(`DEBUG: Element tagName=${tagName}, type=${type}`);


style: Debug console.log statements should be removed from production code

Suggested change

console.log(`DEBUG: Element tagName=${tagName}, type=${type}`);

const tagName = el.tagName.toLowerCase();

const type = (el as HTMLInputElement).type;

return tagName === "input" && type === "file";

greptile-apps · 2025-08-28T16:21:22Z

lib/index.ts

+            },
+          )
+          .catch((e) => {
+            console.log(`DEBUG: evaluate failed:`, e);


style: Debug console.log statements should be removed from production code

Suggested change

console.log(`DEBUG: evaluate failed:`, e);

.catch((e) => {

return false;

});

greptile-apps · 2025-08-28T16:22:07Z

lib/package.json

+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",


logic: Path change from '../dist/' to './' may break builds if corresponding build scripts haven't been updated. Verify that 'pnpm run build-js' outputs to lib/ instead of dist/.

greptile-apps

Greptile Summary

This review covers only the changes made since the last review (commit 318aef5), not the entire PR. The recent changes focus on implementing the feedback from previous reviews regarding package.json path configuration and FileSpec type safety improvements.

The key changes include:

Package.json Path Correction: The entry points have been updated from ../dist/ back to ./ paths (main, module, and types fields), which appears to address the build output concerns raised in the previous review about potential build script mismatches.
FileSpec Type Safety Enhancement: The FileSpec type has been restructured to use proper discriminated unions as suggested in the previous review. The type now enforces three distinct valid combinations: string URLs, objects with required path property, or objects with required name, mimeType, and buffer properties. This prevents invalid partial combinations that could fail at runtime.
Type Guard Implementation: The upload method implementation now includes proper type guards to safely handle the discriminated union FileSpec type, with consistent logic for extracting file names across all three upload strategies (input, chooser, fallback).
Debug Code Cleanup: Console.log statements have been removed from the production code as requested in previous reviews.

These changes address the type safety, build configuration, and code quality concerns identified in previous reviews while maintaining the core upload functionality. The implementation follows TypeScript best practices with discriminated unions and type guards to ensure compile-time safety for the flexible file specification system.

Confidence score: 4/5

This PR addresses previous review feedback effectively with proper type safety and build configuration fixes
Score reflects solid implementation of discriminated unions and removal of debug code, but package.json changes need verification
Pay close attention to build scripts to ensure they output to the correct directory matching the package.json paths

_{3 files reviewed, no comments}

_{Edit Code Review Bot Settings | Greptile}

udaysvc · 2025-09-02T19:48:40Z

@greptileai review again

greptile-apps

Greptile Summary

This review covers only the changes made since the last review, not the entire PR. The latest changes focus on completing the upload functionality implementation with the addition of a test file and some final adjustments.

The changes add a new uploads.test.ts file in the deterministic test suite that provides comprehensive testing for the new upload functionality. This test follows the established testing patterns in the codebase, using the same Stagehand initialization approach with StagehandConfig and proper setup/teardown hooks. The test verifies the upload feature by navigating to a test URL, locating a file input element, uploading a logo.png file, and asserting that both the file name and size are correctly displayed.

The test integrates well with the existing deterministic test infrastructure in the evals/deterministic/tests/browserbase/ directory, maintaining consistency with other Browserbase-specific tests. It uses standard Playwright testing patterns with locators and assertions, and follows the same asynchronous testing approach as other tests in the suite. The test validates the core upload functionality by checking that the uploaded file's metadata (name and non-zero size) is correctly processed and displayed, ensuring the upload method works as expected in a real browser environment.

Confidence score: 4/5

This PR adds well-tested upload functionality with minimal risk of breaking existing features
Score reflects solid implementation with proper testing coverage and integration with existing patterns
The upload test file requires attention to ensure it aligns with the final API and file structure

_{3 files reviewed, no comments}

_{Edit Code Review Bot Settings | Greptile}

udaysvc added 4 commits August 27, 2025 16:34

feat: upload method

64e7170

quick tune

448ff2f

chore: add environment configuration for Stagehand

318aef5

- Set the environment to "BROWSERBASE" in the Stagehand initialization. - Enhanced debugging by adding console logs for element evaluation in the file input check.

udaybuilds47 changed the title ~~Uday/upload~~ upload method for stagehand Aug 28, 2025

greptile-apps bot reviewed Aug 28, 2025

View reviewed changes

udaysvc added 2 commits August 28, 2025 11:24

greptile comment fixes

0ff9eb5

add changeset for upload method feature

5bcbcb1

greptile-apps bot reviewed Aug 28, 2025

View reviewed changes

udaysvc added 3 commits August 28, 2025 14:43

clean

ecd7798

Merge branch 'browserbase:main' into uday/upload

ca9ab89

Merge remote-tracking branch 'origin/main' into uday/upload

cb4ebfb

greptile-apps bot reviewed Sep 2, 2025

View reviewed changes

udaybuilds47 and others added 5 commits September 3, 2025 01:24

Merge branch 'browserbase:main' into uday/upload

3d4f29e

Merge branch 'browserbase:main' into uday/upload

4fc2fac

Merge branch 'browserbase:main' into uday/upload

196fc0b

Merge branch 'browserbase:main' into uday/upload

cf0438c

Merge branch 'browserbase:main' into uday/upload

bce40bc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

upload method for stagehand #1037

upload method for stagehand #1037

Uh oh!

udaybuilds47 commented Aug 28, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Aug 28, 2025 •

edited

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

greptile-apps bot Aug 28, 2025

Uh oh!

greptile-apps bot Aug 28, 2025

Uh oh!

greptile-apps bot Aug 28, 2025

Uh oh!

greptile-apps bot Aug 28, 2025

Uh oh!

greptile-apps bot left a comment

Uh oh!

udaysvc commented Sep 2, 2025

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

upload method for stagehand #1037

Are you sure you want to change the base?

upload method for stagehand #1037

Uh oh!

Conversation

udaybuilds47 commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

stagehand upload method

why

what changed

test plan

notes

usage

impact

Uh oh!

changeset-bot bot commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Greptile Summary

Confidence score: 3/5

Uh oh!

greptile-apps bot Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Greptile Summary

Confidence score: 4/5

Uh oh!

udaysvc commented Sep 2, 2025

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Greptile Summary

Confidence score: 4/5

Uh oh!

Uh oh!

udaybuilds47 commented Aug 28, 2025 •

edited

Loading

changeset-bot bot commented Aug 28, 2025 •

edited

Loading