Add an optional Eve agent as a first-class template app (apps/agent)

[broomva]

Summary

Adds apps/agent — an optional durable backend AI agent built with Eve (Vercel's Apache-2.0 agent framework) — as a first-class template app. This implements the first staged ask from the agent-tier design proposal in #754, and pairs with the Eve add-on guide in #756.

A monorepo is where an agent shines: its tools reuse the same workspace packages, Prisma schema, and validated env keys the apps already use. count-pages demonstrates this by counting Page records through @repo/database.

Why it fits next-forge

• Graceful degradation is the house philosophy — every integration degrades politely when its keys are missing. The agent follows suit at two layers:
  • Model: with an AI Gateway credential (AI_GATEWAY_API_KEY, or the Vercel OIDC token on a deployment) it routes to a real model through the AI Gateway; without one it answers from a deterministic offline fixture. So adding the agent never breaks the first bun run dev for the other apps, and CI runs provider-free.
  • Tool: count-pages returns a disabled result naming the env var to set when the database is unreachable, instead of throwing.
• Optional & self-contained — one more independently-deployable Vercel project, mirroring how every other app deploys.
• Conventions — bun, ultracite/biome clean, @repo/* workspace imports, per-app .env.example, exact eve pin.

What's included

Path	Purpose
apps/agent/agent/agent.ts	Runtime config: gateway model + provider-free mockModel fallback
apps/agent/agent/instructions.md	System prompt
apps/agent/agent/channels/eve.ts	Inbound HTTP channel + auth (Vercel OIDC / localDev / placeholder)
apps/agent/agent/tools/count-pages.ts	Monorepo-native tool over @repo/database
apps/agent/evals/{evals.config,smoke.eval}.ts	Deterministic, provider-free smoke eval
docs/content/docs/apps/agent.mdx	App reference page
README.md, turbo.json, .gitignore	Features entry; .output/** build output; ignore .eve/.output/.workflow-data

Design decisions (open to maintainer direction)

1. server-only workaround, not a @repo/database change (yet). @repo/database's index carries a server-only guard that only the Next.js runtime satisfies — Eve agents run on Nitro. The tool imports @repo/database/generated/client + @repo/database/keys directly to dodge it. The cohesive fix (a guard-free /server subpath on @repo/database, item 2 of Add Eve (durable AI agents) to the stack — an agent tier for next-forge #754) would let the tool import the package root — kept out of this PR to minimize surface; happy to add it if you'd prefer.
2. engines.node >= 24 on the agent package only (Eve requires Node 24+); root stays >=18. A root bump is deferred pending your call in Add Eve (durable AI agents) to the stack — an agent tier for next-forge #754.
3. ai@^7 on the agent — Eve peer-requires ai@7; packages/ai uses ai@6. They coexist via nested resolution (verified under bun); the agent declares its own ai@7.
4. Provider-free CI via mockModel — the offline fixture is deterministic, so eve eval --strict passes with zero API keys. modelContextWindowTokens is set on the mock path (the fixture has no gateway catalog entry).

Test plan

Dogfooded on a stock scaffold under bun (no upstream CI — review is the gate):

• bun install (clean, agent added to workspace)
• bun run build --filter=agent (turbo builds @repo/database → agent) — 2 successful
• eve eval --strict — smoke gates 3/3, provider-free
• tsc --noEmit (agent) — clean
• ultracite check — 307 files, no fixes
• Live curl /eve/v1/session smoke — actions.requested(count-pages) → action.result(disabled: true) → reply cites DATABASE_URL, with modelId: next-forge/offline-fallback confirming the offline fallback

Refs #754 · docs companion #756

[vercel]

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

A member of the Team first needs to authorize it.

[socket-security]

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​eve@​0.20.0
	npm/​ai@​7.0.16

View full report