feat(core)!: require explicit application readiness

Draft
ZR
2d ago
+1332-715

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.