feat(server): migrate control plane to Nitro v3

[RedStar071]

Summary

Start the control-plane migration from oRPC to Nitro v3 and establish ViteHub as the intended provider-neutral sandbox direction for Agent Zero.

• replace the server package's oRPC dependencies and scripts with Nitro v3
• move the HTTP surface toward Nitro-native routes
• preserve the runner boundary so execution providers do not leak into the agent runtime
• document ViteHub's Sandbox / Workspace / Box model as the direction for remote isolated execution

Architecture

Nitro owns the HTTP/control-plane adapter. packages/runner remains the only execution boundary. ViteHub should be integrated behind that boundary so Cloudflare Sandboxes, Vercel Sandbox, and other Box adapters can be selected without coupling the agent state machine to a provider.

ViteHub is currently experimental, so this PR treats it as a replaceable adapter boundary rather than making the core runtime depend directly on provider SDKs.

Notes

This branch is intentionally separate from the GitHub workflow alignment PR and is based directly on main.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is enabled.}

Confidence Score: 3/5

Not safe to merge until the Nitro HTTP routes and documented port behavior are restored.

Two independent runtime checks reproduced client-facing availability failures against the built server. The lint concern was directly disproved by repeated execution of the exact package script.

Files Needing Attention: apps/server/src/index.ts needs configured Nitro HTTP handlers; apps/server/package.json needs startup wiring for AGENT_ZERO_PORT and must satisfy the shared build-toolchain rule.

T-Rex Logs

What T-Rex did

• Generated a proof for a posted P1 finding about Nitro health and task endpoint validation script and server responses.
• Generated a proof for a posted P1 finding about the Nitro port runtime probe, including startup attempts showing port 4040 refused and later connected.
• Validated the server lint workflow with a missing nitro.config.ts by running pnpm lint twice; both runs exited successfully with no diagnostic output.
• Documented runtime validation that health and tasks endpoints return 404 when nitro.config.ts is absent, and noted that a fixture was removed with no source files retained beyond artifacts.
• Demonstrated port probing behavior using the zero-port probe script, showing 4040 and 3000 port behavior before and after setting NITRO_PORT.

_{Ran code and verified through T-Rex}

Prompt To Fix All With AI

### Issue 1
apps/server/src/index.ts:1
**Nitro routes are never registered**
The entrypoint only re-exports task helpers and does not register Nitro handlers. A built and running server returns `404 Not Found` for `GET /health`, `GET /tasks`, and `GET /tasks/missing-task`, so the control plane is unreachable over HTTP. Add configured Nitro route handlers for the health and task API contract and cover them with an HTTP-level test.
### Issue 2
apps/server/package.json:10
**Documented server port is ignored**
The new startup command launches Nitro without mapping the documented `AGENT_ZERO_PORT` variable to Nitro's port configuration. With `AGENT_ZERO_PORT=4040`, the built server refuses connections on 4040 and instead listens on port 3000. Configure startup to honor `AGENT_ZERO_PORT`, or update the documented configuration contract consistently, and add a listener regression test.
### Issue 3
apps/server/package.json:6
**Build bypasses mandated tsdown configuration**
Changing this package to invoke `nitro build` directly bypasses its `tsdown.config.ts` and the shared tsdown configuration required by the repository, leaving the server outside the standardized package build toolchain.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "fix(repo): drop llms.txt from required r..." | Re-trigger Greptile}

Greptile also left 3 inline comments on this PR.

Context used:

• Context used - CLAUDE.md (source)

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	nitro@​3.0.260522-beta

View full report

[greptile-apps]

Nitro routes are never registered

The entrypoint only re-exports task helpers and does not register Nitro handlers. A built and running server returns 404 Not Found for GET /health, GET /tasks, and GET /tasks/missing-task, so the control plane is unreachable over HTTP. Add configured Nitro route handlers for the health and task API contract and cover them with an HTTP-level test.

Artifacts

Nitro health and task endpoint validation script

• Authored Bash script that builds the Nitro application, starts it, and captures HTTP responses for health and task control-plane requests, ending with the takeaway that it exercises the server rather than only unit helpers.

Nitro server control-plane responses before an attempted route fixture

• Captured build and live HTTP output showing GET /health, GET /tasks, and GET /tasks/missing-task each return 404 Not Found, ending with the takeaway that the committed server exposes no control-plane routes.

Nitro server responses after an attempted conventional Nitro route fixture

• Captured rebuild and live HTTP output after a temporary `apps/server/server/api` fixture, showing all three URLs still return 404 Not Found because this bare Nitro configuration does not discover that directory, ending with the takeaway that a correctly configured route registration is required.

_{Ran code and verified through T-Rex}

Prompt To Fix With AI

This is a comment left during a code review.
Path: apps/server/src/index.ts
Line: 1
Comment:
**Nitro routes are never registered**
The entrypoint only re-exports task helpers and does not register Nitro handlers. A built and running server returns `404 Not Found` for `GET /health`, `GET /tasks`, and `GET /tasks/missing-task`, so the control plane is unreachable over HTTP. Add configured Nitro route handlers for the health and task API contract and cover them with an HTTP-level test.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Documented server port is ignored

The new startup command launches Nitro without mapping the documented AGENT_ZERO_PORT variable to Nitro's port configuration. With AGENT_ZERO_PORT=4040, the built server refuses connections on 4040 and instead listens on port 3000. Configure startup to honor AGENT_ZERO_PORT, or update the documented configuration contract consistently, and add a listener regression test.

Artifacts

Nitro port runtime probe script

• The authored executable starts the built server with a chosen environment variable and performs isolated real TCP port checks, proving which listener was created.

AGENT_ZERO_PORT startup output showing port 4040 refused

• The executed AGENT_ZERO_PORT=4040 run shows 4040 refused, 3000 connected, and Nitro listening on 3000, confirming the documented variable is ignored.

NITRO_PORT startup output showing port 4040 connected

• The executed NITRO_PORT=4040 control run shows 4040 connected, 3000 refused, and Nitro listening on 4040, confirming the runtime supports 4040 through its actual variable.

_{Ran code and verified through T-Rex}

Prompt To Fix With AI

This is a comment left during a code review.
Path: apps/server/package.json
Line: 10
Comment:
**Documented server port is ignored**
The new startup command launches Nitro without mapping the documented `AGENT_ZERO_PORT` variable to Nitro's port configuration. With `AGENT_ZERO_PORT=4040`, the built server refuses connections on 4040 and instead listens on port 3000. Configure startup to honor `AGENT_ZERO_PORT`, or update the documented configuration contract consistently, and add a listener regression test.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Build bypasses mandated tsdown configuration

Changing this package to invoke nitro build directly bypasses its tsdown.config.ts and the shared tsdown configuration required by the repository, leaving the server outside the standardized package build toolchain.

Context Used: CLAUDE.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: apps/server/package.json
Line: 6
Comment:
**Build bypasses mandated tsdown configuration**
Changing this package to invoke `nitro build` directly bypasses its `tsdown.config.ts` and the shared tsdown configuration required by the repository, leaving the server outside the standardized package build toolchain.
**Context Used:** CLAUDE.md ([source](https://github.com/wolfstar-project/agent-zero/blob/main/CLAUDE.md))
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!