Add back default extract schema

[miguelg719]

Summary

• default extract calls to an object with a required string extraction field in TypeScript and Python
• use the same schema when Go callers pass a nil schema
• preserve explicit schema validation and add wire-level regression coverage for all three SDKs

Verification

• TypeScript: object-wrapper suite (42 passed), formatting, lint
• Python: ruff, ty, full pytest suite (263 passed, 1 skipped)
• Go: focused extract and envelope regression tests

Notes

• The broader TypeScript unit run reached 117 passing tests; its package-contract test could not complete its isolated dependency install in this environment.
• The TypeScript package build compiled JS and declarations successfully, then stopped because the generated extension artifact was not present.

---

Summary by cubic

Restore a protocol-level default extract schema so extract() works without a schema and returns { extraction: string } by default across @browserbasehq/stagehand, @browserbasehq/stagehand-python, and @browserbasehq/stagehand-go. Makes the schema optional in the protocol and server, adds type-safe defaults/overloads, and updates docs/tests for Linear STG-2747.

• New Features

  • Protocol/server: embed default JSON schema ({ extraction: string }), make schema optional, and apply the default in the router and wire models.
  • TypeScript (@browserbasehq/stagehand): default to DefaultExtractDataSchema when no Zod schema is provided, accept options as the second arg, validate with the chosen schema, and only send schema when custom.
  • Python (@browserbasehq/stagehand-python): add DefaultExtract model and overload; generated params default to the protocol schema; only send schema when custom.
  • Go (@browserbasehq/stagehand-go): omit schema by default via omitempty; client sets params only when a custom schema is provided.
  • Docs/tests: mark schema optional and document the default; adjust TS docs/tests to reflect schema-bearing overload return type; add server/protocol and SDK tests for default behavior.

• Bug Fixes

  • Go: preserve an explicitly empty schema ({}) and ensure it is sent on the wire.

^{Written for commit 838df58. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 838df58

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]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[miguelg719]

@cubic-dev-ai

[cubic-dev-ai]

@cubic-dev-ai

@miguelg719 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

All reported issues were addressed across 10 files

Architecture diagram

sequenceDiagram
    participant TSClient as TypeScript SDK Client
    participant PyClient as Python SDK Client
    participant GoClient as Go SDK Client
    participant Stagehand as Stagehand (core)
    participant ProtocolRPC as Protocol RPC Client
    participant DocSite as Documentation Site

    Note over TSClient,GoClient: PR: Default extract schema across all 3 SDKs

    alt TypeScript call with no schema
        TSClient->>TSClient: Uses defaultExtractSchema (z.object({ extraction: z.string() }))
        TSClient->>Stagehand: extract(instruction, schema = undefined)
        Stagehand->>Stagehand: resolvedSchema = defaultExtractSchema
        Stagehand->>Stagehand: Generate JSON schema from resolvedSchema
        Stagehand->>ProtocolRPC: stagehand.extract with schema = { type: "object", properties: { extraction: { type: "string" } }, required: ["extraction"], additionalProperties: false }
        ProtocolRPC-->>Stagehand: ExtractResult { data: { extraction: "..." } }
        Stagehand->>Stagehand: Parse response with resolvedSchema
        Stagehand-->>TSClient: ExtractResult<typeof defaultExtractSchema>
    else Python call with default schema class
        PyClient->>PyClient: Uses DefaultExtract model
        PyClient->>Stagehand: extract(instruction, schema = DefaultExtract)
        Stagehand->>Stagehand: schema is DefaultExtract → use _DEFAULT_EXTRACT_SCHEMA dict
        Stagehand->>ProtocolRPC: stagehand.extract with schema = { "type": "object", "properties": { "extraction": { "type": "string" } }, "required": ["extraction"], "additionalProperties": false }
        ProtocolRPC-->>Stagehand: ExtractResult { data: { extraction: "..." } }
        Stagehand-->>PyClient: ExtractResult[DefaultExtract]
    else Go call with nil schema
        GoClient->>GoClient: schema parameter = nil
        GoClient->>Stagehand: Extract(instruction, schema = nil)
        Stagehand->>Stagehand: schema == nil → Use defaultExtractSchema() JSON
        Stagehand->>ProtocolRPC: stagehand.extract with schema = { "type": "object", "properties": { "extraction": { "type": "string" } }, "required": ["extraction"], "additionalProperties": false }
        ProtocolRPC-->>Stagehand: ExtractResult { Data: { extraction: "..." } }
        Stagehand-->>GoClient: ExtractResult
    end

    Note over GoClient,GoClient: Explicit empty schema path (Go only)
    alt Go: schema = json.RawMessage{} (empty)
        GoClient->>Stagehand: Extract(instruction, schema = {})
        Stagehand->>Stagehand: schema is not nil → Preserve empty schema
        Stagehand->>ProtocolRPC: stagehand.extract with schema = {}
        ProtocolRPC-->>Stagehand: ExtractResult { Data: {} }
        Stagehand-->>GoClient: ExtractResult with empty data
    end

    Note over TSClient,PyClient: TypeScript: generic overload guard
    alt TS caller tries generic without runtime schema
        TSClient->>TSClient: extract<CustomSchema>(instruction, undefined)
        TSClient->>TSClient: @ts-expect-error – TypeScript prevents this
        Note over TSClient: Compile-time type safety preserved
    end

    DocSite->>DocSite: Updated docs: schema param marked optional, describes default

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 14 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>