[STG-1053] [server] Use fastify-zod-openapi + zod v4 for openapi generation #1420
Conversation
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 30 files
Prompt for AI agents (all 1 issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="packages/core/lib/v3/types/private/api.ts">
<violation number="1" location="packages/core/lib/v3/types/private/api.ts:36">
P2: The `browser` type definition doesn't match the server schema. In the server, `type` is optional and there are additional fields (`cdpUrl`, `launchOptions`) that the core interface doesn't expose. Consider aligning the types:
```typescript
browser?: {
type?: "local" | "browserbase";
cdpUrl?: string;
launchOptions?: Record<string, unknown>;
};
```</violation>
</file>
Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR
Greptile OverviewGreptile SummaryThis PR modernizes the Stagehand server API by migrating from Zod v3 to v4 and implementing automated OpenAPI spec generation using fastify-zod-openapi. The changes address significant technical debt where the hand-maintained OpenAPI file had become stale and validation was disabled. Key changes include upgrading the server to use Zod v4 schemas with fastify-zod-openapi for automatic documentation generation, standardizing all API responses to use a The migration spans the entire codebase, touching core types, server routes, evaluation systems, and examples to ensure consistency. This enables stricter request/response validation, better error reporting with structured Zod issues, and automatic documentation that stays in sync with the actual API implementation. Important Files Changed
Confidence score: 4/5
Sequence DiagramsequenceDiagram
participant User
participant LangchainClient as "Langchain Client"
participant V3 as "Stagehand V3"
participant Handler as "Extract Handler"
participant OpenAI as "OpenAI API"
participant Page as "Browser Page"
User->>V3: "new Stagehand(config)"
User->>V3: "init()"
V3->>Page: "goto('https://news.ycombinator.com')"
User->>V3: "extract('extract the title of the top story', schema)"
V3->>Handler: "extract(params)"
Handler->>Page: "Take screenshot"
Page-->>Handler: "Screenshot data"
Handler->>LangchainClient: "Generate completion with schema"
LangchainClient->>OpenAI: "API call with prompt"
OpenAI-->>LangchainClient: "Structured response"
LangchainClient-->>Handler: "Parsed result"
Handler-->>V3: "Extract result"
V3-->>User: "{ story: 'top story title' }"
User->>V3: "act('click the first story')"
V3->>Handler: "act(instruction)"
Handler->>Page: "Take screenshot"
Page-->>Handler: "Screenshot data"
Handler->>LangchainClient: "Generate action plan"
LangchainClient->>OpenAI: "API call with instruction"
OpenAI-->>LangchainClient: "Action response"
LangchainClient-->>Handler: "Action plan"
Handler->>Page: "Execute click action"
Page-->>Handler: "Action result"
Handler-->>V3: "Act result"
V3-->>User: "Action completion"
User->>V3: "close()"
V3->>Page: "Close browser session"
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
monadoid
force-pushed
the
openapi_spec_generation
branch
from
fd35502 to
5150806
Compare
… include more detail
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
|
I got claude to do a deep-dive review to look for any unintentional changes introduced in 
|
|
|
||
| import { error } from "./response.js"; | ||
|
|
||
| const INTERNAL_SERVER_ERROR_STATUS_CODE = 500; |
There was a problem hiding this comment.
not sure if we have the same ts / lints restrictions here, but we should. Would it be useful to use http-status-codes rather than declare these?
| verbose?: 0 | 1 | 2; | ||
| selfHeal?: boolean; | ||
| // V2 compatibility fields - only included because the server imports this type and supports V2 | ||
| waitForCaptchaSolves?: boolean; |
There was a problem hiding this comment.
waitForCaptchaSolves & actTimeoutMs are both v2 params
✱ Stainless preview buildsThis PR will update the
|
why
what changed
Future stuff:
test plan
Ran eval suite - passing
Summary by cubic
Generates an OpenAPI 3.1 spec from live Zod v4 schemas with strict request/response validation. /v1/sessions/start now accepts browser.type and can return connectUrl; cdpUrl is removed. Addresses STG-1053.
New Features
Migration
Written for commit 2ae58ab. Summary will update automatically on new commits.