feat(core)!: require explicit application readiness

[zrosenbauer]

PR Checklist

• Commit message follows repository conventions.

Bugs / Features

• Lifecycle and real HTTP/WebSocket regression tests added.
• Application lifecycle and server architecture references updated.
• Changeset included for core and server packages.

What is the current behavior?

Application construction starts resources implicitly. Readiness and cleanup can race, telemetry operations can prevent one another from running, and listener shutdown can complete before all resources have closed.

What is the new behavior?

• Require await app.ready() to start workspaces, telemetry, transports, and servers, including applications without an HTTP server.
• Share startup and shutdown promises; clean up partial startup failures and signal handlers.
• Drain HTTP and WebSocket resources before independently flushing and shutting down traces and logs.
• Await real Hono listening readiness and listener closure, including partially started servers.
• Close MCP transports only once.

Testing

• Core: 1,599 tests, including 12 lifecycle cases and type tests.
• Server-core: 130 tests; Hono: 78 tests.
• Two real HTTP/WebSocket lifecycle end-to-end tests passed.
• Core/server builds, source types, and built-package consumer types passed.
• Repository lint, formatting, and whitespace checks passed.

Notes for reviewers

Layer 2 of 4. Depends on #1454; merge that PR first.

This cross-fork draft targets upstream next, so its diff initially includes layer 1. The lifecycle-specific commit is d61ff5da. Rebase this branch onto next after #1454 merges, preserving the lifecycle commit.

Review order: authoring API → explicit lifecycle → examples/scaffolding → documentation.

The untouched serverless-Hono routes have existing type errors involving ContentfulStatusCode and stepId; those are outside these lifecycle changes.

---

Summary by cubic

Requires explicit application readiness: constructing an application no longer starts workspaces, telemetry, transports, or servers; call and await app.ready() instead. Also introduces defineAgent, defineTool, defineWorkflow, and the voltagent() bootstrap factory as the canonical authoring API.

Lifecycle

• app.shutdown() is idempotent, waits for in-flight startup, and flushes traces and logs before shutting down telemetry.
• Startup errors reject the readiness promise and clean up partially initialized resources; repeated readiness and shutdown calls share internal promises.
• HTTP readiness waits for the listening event; shutdown drains requests and closes connected WebSocket clients before flushing telemetry, and MCP transports are closed only once.

Migration

• Replace new Agent(...) with defineAgent(...), tool(...) with defineTool(...), createWorkflow(...) with defineWorkflow(...), and new VoltAgent(...) with await voltagent(...).ready().
• Agent and VoltAgent are now type-only exports; the default export is the voltagent factory, and the old tool and createWorkflow exports are removed.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: d61ff5d

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

This PR includes changesets to release 4 packages

Name	Type
@voltagent/core	Major
@voltagent/scorers	Patch
@voltagent/server-hono	Patch
@voltagent/server-core	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

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}