[feat]: add interactive chat REPL via stagehand.chat() and stagehand.pause() (please ignore)

[chrisreadsf]

Adds a terminal REPL that pauses script execution and lets you run stagehand and page commands interactively. Press Enter to resume.

Supported commands:

• stagehand.act("..."), stagehand.extract("..."), stagehand.observe("...")
• page.url(), page.title(), page.goto("..."), page.reload()

why

what changed

test plan

[changeset-bot]

⚠️ No Changeset found

Latest commit: 261adc9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[cubic-dev-ai]

1 issue found across 2 files

Confidence score: 2/5

• High-severity, high-confidence issue in packages/core/lib/v3/chat.ts: raw exception/result messages may be shown in the REPL instead of sanitized typed errors, which can expose internal details to users.
• This creates a meaningful security and user-impact risk, so merge confidence is reduced until errors are mapped to safe, sanitized messages.
• Pay close attention to packages/core/lib/v3/chat.ts - ensure exception handling consistently sanitizes output before displaying it in the REPL.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/chat.ts">

<violation number="1" location="packages/core/lib/v3/chat.ts:128">
P1: Custom agent: **Exception and error message sanitization**

Do not print raw exception/result messages to the REPL. Map errors to sanitized, typed safe messages before showing them to users.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Script as User Script
    participant V3 as Stagehand (V3)
    participant Chat as Chat REPL (chat.ts)
    participant TTY as Terminal (stdin/stdout)
    participant Page as Browser Page

    Note over Script,Page: NEW: Interactive Debugging Flow

    Script->>V3: pause() / chat()
    
    V3->>V3: NEW: resolvePage()
    V3->>Chat: NEW: chat({ act, extract, observe, page })
    
    alt STDIN is NOT a TTY
        Chat-->>V3: Log warning & Skip
        V3-->>Script: Resume execution
    else STDIN is a TTY
        Chat->>TTY: Print "Stagehand paused..."
        
        loop REPL loop (Until Enter is pressed)
            Chat->>TTY: Prompt "🤘 "
            TTY-->>Chat: User Input (e.g., "page.url()")
            
            alt Command: help
                Chat->>TTY: Print available commands
            else Command: Known (e.g., act, page.goto)
                Chat->>Chat: NEW: resolve(input)
                
                alt Interaction: Page
                    Chat->>Page: call method (url, title, goto, etc.)
                    Page-->>Chat: result
                else Interaction: Stagehand
                    Chat->>V3: call method (act, extract, observe)
                    V3-->>Chat: ActResult / Extraction
                end
                
                Chat->>TTY: Print formatted result (colorized)
            else Command: Empty (Enter)
                Chat->>Chat: Break loop
            else Command: Unknown
                Chat->>TTY: Print "Unknown command"
            end
        end

        Chat-->>V3: Close REPL
        V3-->>Script: Resume execution
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: Custom agent: Exception and error message sanitization

Do not print raw exception/result messages to the REPL. Map errors to sanitized, typed safe messages before showing them to users.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/core/lib/v3/chat.ts, line 128:

<comment>Do not print raw exception/result messages to the REPL. Map errors to sanitized, typed safe messages before showing them to users.</comment>

<file context>
@@ -0,0 +1,132 @@
+    try {
+      console.log(await commands[key](ctx, line.trim()));
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.log(red(`  ✗ ${msg}`));
+    }
</file context>