Expose world helpers via workflow/api (v2)

[artimath]

PR: Expose world helpers via workflow/api (v2)

Summary

• Surface getWorld plus every World helper (runs/steps/events/hooks/queue/streams/start) directly from workflow/api, so application code can manage runs without reimplementing createWorld.
• Add Vitest coverage that stubs setWorld to assert each helper delegates correctly and specifically exercises the “list runs then cancel” flow requested for Next.js/server usage.
• Document the new API via a dedicated “World helpers” reference page, updated foundations guide example, and API index entry; include testing guidance about swapping worlds.
• Record the change with a Changeset so release automation bumps the workflow package.

Use Cases Addressed

1. Programmatic run management: Next.js routes (or any server code) can list, inspect, pause/resume, or cancel active runs using listRuns, cancelRun, etc., without importing from workflow/runtime.
2. Accessing the default world: Users asking “is there a public API to access the active World?” can now call getWorld() from workflow/api, matching CLI behavior across dev/test/prod setups.
3. Queue/stream control: Advanced tooling can enqueue messages or stream data via the same helpers the runtime uses (queue, createQueueHandler, writeToStream, etc.).
4. Testability: Teams can stub setWorld in tests while still using the exported helpers, ensuring parity with production behavior.

Implementation Details

• packages/workflow/src/api.ts now imports the relevant types from @workflow/world, re-exports them, and defines thin wrappers for every World subfunction plus startWorld.
• Added @workflow/world to packages/workflow/package.json dependencies and synced pnpm-lock.yaml.
• Created packages/workflow/src/api.test.ts with full delegation coverage and the “list -> cancel” scenario.
• Authored docs/content/docs/api-reference/workflow-api/world.mdx, updated the API index cards, and inserted a new “Programmatically list and control runs” section in starting-workflows.mdx.
• Added .changeset/expose-world-helpers.md so the workflow package gets a patch bump.

Verification

• pnpm --filter workflow test -- src/api.test.ts
• pnpm --filter workflow typecheck
• pnpm biome check packages/workflow/src/api.ts packages/workflow/src/api.test.ts

Notes

• The PR remains in draft status until review; description mirrored here for convenience.

[changeset-bot]

🦋 Changeset detected

Latest commit: 60bb0b4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
workflow	Patch
@workflow/ai	Patch
@workflow/world-testing	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

@artimath is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.