Gal Schlezinger

This commit **refactors the build process** for the **`@vercel/sandbox` package**, migrating it from custom scripts to `tsdown` for generating unbundled dual ESM and CJS outputs. The `package.json` is updated with explicit `exports` maps, ensuring that Node.js `import` statements correctly resolve `.js` files and `require` statements resolve `.cjs` files. This **modernizes the module distribution** for the SDK, improving compatibility and providing robust support for both module systems. Additionally, internal import paths within the package are updated to include `.js` extensions, and new tests are introduced to verify the correct package export resolution.

This commit introduces a **new capability** to specify default environment variables during sandbox creation. It **extends the `Sandbox.create()` API** by adding an `env` parameter to `BaseCreateSandboxParams`, allowing programmatic definition of environment variables for new sandboxes. Concurrently, the **`sandbox create` CLI command** now supports `--env` and `-e` flags, enabling users to configure these variables directly from the command line. This enhancement provides greater flexibility for pre-configuring sandbox environments with necessary default settings, affecting the `vercel-sandbox` and `sandbox` packages.

This commit **upgrades the `cmd-ts` dependency** in the **CLI** (`packages/sandbox`) from version 0.14.3 to 0.15.0, enabling a significant **feature enhancement** to the command-line interface. It adopts the new `vercelFormatter` to standardize the **CLI help output**, aligning it with the familiar Vercel CLI style for improved consistency and user experience. This involves extensive **refactoring** across various commands, such as `config`, `cp`, `exec`, and `list`, to reorder arguments and flags for optimal display. Additionally, examples are added to the main application and the `create` command, ensuring all CLI commands are comprehensively documented with the new, improved formatting.

This commit **fixes** a broken link within the **`examples/axum`** module's `README.md` file. Previously, the URL provided for the live Axum example was returning a 404 error, making the example inaccessible to users. This change updates the `README.md` to reflect the correct and working deployment address for the live application. The **documentation fix** ensures that users can now successfully access and view the deployed Axum example, improving the usability and reliability of the project's examples.

This commit **significantly improves the `sandbox` CLI client's API error reporting** by parsing the JSON response body to extract and display specific error messages. Instead of a generic "Sandbox API request failed" message, users will now receive the actual, detailed error provided by the API, such as "Invalid network policy". This **enhancement** provides a **more informative and actionable user experience** when API requests fail, making it much easier to diagnose and resolve issues. The core logic for this **new capability** is implemented in the `handleApiError` function within `packages/sandbox/src/client.ts`, leveraging a Zod schema for robust parsing.

This commit introduces a **new capability** to the **CLI `sandbox create` command**, significantly enhancing user experience by displaying the associated **team and project** slugs, along with any mapped ports, in a clear, framed output format. It improves the **`sandbox` module's user feedback** by enhancing the scope inference mechanism to extract these details from OIDC token claims and making them available to commands. Additionally, it **refactors** the output of `sandbox run` and `sandbox exec` commands and the interactive shell to remove redundant sandbox IDs, providing a more concise and informative user interface. This change directly addresses user confusion about sandbox ownership and location, resolving issues like EC-4761.

This commit **fixes a critical bug** in the **authentication** and **scope inference** mechanisms within the `sandbox` package. Previously, after an OIDC token refresh, the system would use the new token for API calls but infer the team/project scope from a stale environment variable, causing intermittent 403 errors. The `inferScope` utility in `packages/sandbox/src/util/infer-scope.ts` now directly parses JWT claims from the active token, ensuring the **scope always matches the token's actual claims**. This **bug fix** prevents authorization failures and improves the reliability of API interactions after token refreshes, with new tests added to validate this behavior.

This commit **fixes** an issue in the **core telemetry system** where **workflow suspensions** were incorrectly reported as errors in **OpenTelemetry traces**. The `trace` function in `packages/core/src/telemetry.ts` now correctly identifies `WorkflowSuspension` as a non-error state, setting the span status to `OK` and applying specific attributes. This change, along with the introduction of new **semantic convention constants** in `packages/core/src/telemetry/semantic-conventions.ts`, ensures more accurate **OpenTelemetry monitoring** by preventing false-positive error alerts and providing clearer insights into workflow execution states.

This commit introduces significant **OpenTelemetry observability enhancements** to the **core runtime's queue operations**. It integrates **span links** and **message IDs** into spans generated by `workflowEntrypoint` and `stepEntrypoint`, enabling clearer tracing and correlation of asynchronous tasks. Additionally, this **new capability** adds **queue overhead metrics** by tracking message request times, providing crucial performance insights into message queuing latency. These changes, supported by new telemetry utilities and semantic conventions, greatly improve the ability to debug and monitor the performance of queued workflows and steps.

This commit **enhances the responsiveness** of the **`world-postgres`** service by **reducing the polling interval** for `pg-boss` jobs. Specifically, the `createQueue` function within `packages/world-postgres/src/queue.ts` now configures `pg-boss` to poll for new jobs every 0.5 seconds. This **performance optimization** ensures that queued tasks are picked up and processed with significantly **lower latency**, improving the overall efficiency of the queue management system.

This commit addresses several issues and significantly enhances the testing infrastructure, particularly for the **Postgres world** and **core runtime**. It **migrates the Postgres world's data serialization from JSONB to CBOR** to resolve a critical null byte handling bug, updates Drizzle ORM schema and usage, and ensures **hook metadata is correctly stored** within the `world-postgres` storage. The **core runtime also receives a refactor of its world configuration caching mechanism** to use global symbols, preventing module caching inconsistencies, and introduces a **new `TypedHook` interface for improved type safety**, alongside **correcting the initial attempt count for workflow steps to 0**. These **bug fixes and enhancements** are validated by extensive **new test suites** in `world-testing` covering **workflow hooks**, **error handling**, and **null byte serialization**, with the **Postgres world** now integrated into all workbench packages for comprehensive testing.

This commit introduces a **new capability** to ensure **transaction-like behavior** for top-level commands within the **core runtime** of the application. It achieves this by integrating `waitUntil` wrapping into critical execution paths. Specifically, the `start` and `resumeHook` functions in `packages/core/src/runtime` are now wrapped with a new `waitedUntil` utility. This ensures that all asynchronous operations initiated by these functions complete before the serverless function halts, preventing premature termination and improving the reliability of serverless function execution.

This commit introduces a **new capability** by **stubbing the `workflow/api` package** within the **`workflow` module**, making its functions referencable in a workflow context. It creates placeholder implementations for API functions like `Run`, `getRun`, and `start` in `packages/workflow/src/api-workflow.ts` that are designed to throw errors if invoked, preventing accidental execution of unimplemented logic. This **enables future development** of durable workflow operations by providing an importable API surface, while explicitly disallowing runtime calls until proper implementations are in place. The `packages/workflow/package.json` is updated to export this new `workflow` API entry point.

This commit **improves the readability of documentation info callouts** when viewed in dark mode. It **adjusts the text color** within the `Callout` component, specifically for `info` type callouts defined in `docs/components/ui/callout.tsx`. This **style improvement** is a **maintenance task** that enhances the user experience by ensuring better contrast and legibility for users browsing the documentation with dark mode enabled.

This commit **updates the documentation** for the **'Storytime Slackbot' template** by modifying the link in `docs/app/(home)/components/templates/index.tsx`. Previously, the link directed users to the GitHub repository, but it now points to a more comprehensive **Vercel guide**. This **documentation maintenance** improves the user experience by providing a richer, more informative resource for users interested in learning about or implementing the template.

This commit **resolves a minor UI inconsistency** within the **documentation sidebar navigation**. It **adjusts the styling** in `docs/components/layout/docs.tsx` to ensure that chevron icons correctly point to the right when a document directory is in its closed state. This **visual refinement** improves the clarity and intuitiveness of the documentation's expandable navigation elements, enhancing the overall user experience.

This commit significantly **enhances and expands the documentation** related to the project's "World" deployment concept. It **rewrites and simplifies the main "World interface" explanation** in `docs/content/docs/deploying/world/index.mdx`, introducing new sections for choosing and community worlds. Crucially, **detailed documentation for the Postgres World** is added in `docs/content/docs/deploying/world/postgres-world.mdx`, covering usage and configuration. To support these updates, a **new `wip` type is introduced to the `Callout` UI component** in `docs/components/ui/callout.tsx` for highlighting work-in-progress content, and the `vercel-world.mdx` page now includes a link to the Workflow documentation. These **documentation updates** improve clarity, provide essential new information, and enhance the overall user experience for understanding and deploying various "World" configurations.

This commit performs essential **documentation maintenance** by **fixing numerous typos** and **improving the accuracy of code examples** across the project's guides. It **corrects syntax errors**, standardizes function names (e.g., `callAPI` to `callApi`), and rectifies import paths within code snippets in the **foundations documentation** covering control flow, errors, serialization, and workflows. Additionally, spelling mistakes are addressed in the **foundations overview**, **getting started overview**, and the **Nitro getting started guide**, ensuring a more precise and reliable resource for users. This work enhances the overall clarity and correctness of the **developer documentation**.

This commit **fixes a critical module resolution bug** within the **OIDC package** by explicitly adding `.js` file extensions to dynamic import paths. Specifically, the `getVercelOidcToken` function in `packages/oidc/src/get-vercel-oidc-token.ts` was updated to ensure compatibility with bundlers that enforce ESM import rules. This **bug fix** prevents "Cannot find module" errors, allowing projects to successfully build and utilize the OIDC token retrieval functionality. The change ensures robust module loading and **improves the reliability of the OIDC integration**.

This commit **refactors** the **AWS OIDC credentials provider** in `packages/functions` by extracting the dynamic import of `@aws-sdk/credential-provider-web-identity` into a new async loader function, `loadAwsCredentialProviderWebIdentity`. This change introduces robust error handling, providing a clear message if the package is unavailable. The primary goal is to **optimize bundle size** and **enhance runtime stability** by explicitly informing bundlers that this AWS dependency is optional, thus preventing its inclusion and potential errors in environments not requiring AWS support. Documentation for the OIDC module has also been adjusted.