Stagehand style API

[platonai]

Purpose

Stagehand compatible, so Suna can use Browser4 directly.

Browser Init APIs:

• healthy
• init

Browser Automation APIs:

• navigate
• screenshot
• act
• extract

We can use the existing commands API.

Possible changes:

• add CommandRequest.sessionId to track a session, each session relative to an active page (WebDriver).
• SPA mode, the pulsar session do not timeout
• the client can do the iteration: navigate, act, screenshot, extract, which is very typical in AI agents

Stagehand SDK:

interface Page extends Omit<Page$1, "on"> {
    act(action: string): Promise<ActResult>;
    act(options: ActOptions): Promise<ActResult>;
    act(observation: ObserveResult): Promise<ActResult>;
    extract(instruction: string): Promise<ExtractResult<typeof defaultExtractSchema>>;
    extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
    extract(): Promise<ExtractResult<typeof pageTextSchema>>;
    observe(): Promise<ObserveResult[]>;
    observe(instruction: string): Promise<ObserveResult[]>;
    observe(options?: ObserveOptions): Promise<ObserveResult[]>;
    on: {
        (event: "popup", listener: (page: Page) => unknown): Page;
    } & Page$1["on"];
}