Simplify acknowledgement results

[monadoid]

Why

Side-effect-only RPC methods currently return several method-specific success objects:

{ ok: true }
{ closed: true }
{ clicked: true }
{ filled: true }

Although fields such as clicked and closed look descriptive, they do not communicate an additional outcome. These fields are literals: on a successful response, their value can only be true. If the operation fails, the call produces a JSON-RPC error instead of returning a result with the field set to false.

As a result, even a caller with access to .clicked would never need to check it:

try {
  await page.locator("button").click();
  // The click succeeded because the awaited operation completed.
  // A `clicked` field here could only repeat that fact as `true`.
} catch (error) {
  // The click failed.
}

There is no third code path where the call succeeds but returns { clicked: false }. The method being called already identifies the operation, and successful completion already acknowledges that it happened. Returning true expresses the same contract without a separate result shape for every side-effect-only method.

The public TypeScript and Python SDKs continue exposing these methods as Promise<void> and None, so this does not change their caller-facing APIs.

What changed

• Add one shared acknowledgement schema:

  export const AcknowledgementResultSchema = z.literal(true).meta({
    id: "AcknowledgementResult",
  });

• Point all 28 side-effect-only RPC methods directly at the shared schema.

• Return true as const from the corresponding server controller and runtime methods.

• Remove 12 obsolete result schemas and their generated types.

• Regenerate stagehand.v4.json and the Python protocol models.

• Keep all public TypeScript and Python method signatures unchanged.

Before and after

Wire protocol

Before:

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "clicked": true
  }
}

After:

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": true
}

Failures remain normal JSON-RPC errors and never return result: false:

{
  "jsonrpc": "2.0",
  "id": 12,
  "error": {
    "code": -32603,
    "message": "Element is not clickable"
  }
}

[changeset-bot]

⚠️ No Changeset found

Latest commit: a84b5ff

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 across 28 files

Architecture diagram

sequenceDiagram
    participant SDK as SDK Client<br/>(TypeScript / Python)
    participant Transport as JSON‑RPC Transport
    participant Router as Server Router
    participant Controller as Controller
    participant Runtime as Runtime
    participant Schema as AcknowledgementResultSchema

    Note over SDK,Schema: CHANGED: All side‑effect‑only methods return the literal `true`

    SDK->>Transport: jsonrpc request<br/>{ method: "locator.click", params }
    Transport->>Router: dispatch to handler
    Router->>Controller: invoke handler
    Controller->>Runtime: locatorClick(params)
    Runtime-->>Controller: true as const
    Controller-->>Router: result: true
    Router->>Schema: validate result (z.literal(true))
    Schema-->>Router: valid
    Router-->>Transport: jsonrpc response<br/>{ result: true }
    Transport-->>SDK: response received
    SDK->>SDK: unwrap to void/None

    alt Error during execution
        Runtime-->>Controller: throw error
        Controller-->>Router: jsonrpc error
        Router-->>Transport: jsonrpc error response<br/>{ error: { code, message } }
        Transport-->>SDK: error thrown
    end

Loading

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

Re-trigger cubic</sub>

[monadoid]

Closing this PR; #2434 has been rebased to stand alone against v4-spike.