Add /api/dev/session for curl-based testing

Summary

• Adds POST /api/dev/session, a dev-only endpoint that mints a real Better Auth session cookie for a dedicated bot user (id = __test_bot__, username = test-bot) so the app can be exercised end-to-end from the command line.
• Adds scripts/test-agent.sh — a self-contained smoke test that mints the cookie, creates a chat session, waits for the Vercel sandbox, sends a message, and streams the response. Supports --session SESSION_ID for follow-up turns to an existing chat.
• Adds docs/agents/endpoints.md — the curl-based testing guide, linked from AGENTS.md.

Why

Today every feature is only really testable through the browser. That blocks coding agents (and humans on the CLI) from verifying changes without OAuth-signing-in and clicking around. With this endpoint, anything the browser can do is reachable from curl with a real session cookie — same code path, same auth, same workflow.

Security boundary

• Cannot impersonate real users. Only ever mints a session for __test_bot__. The id is a 12-char sentinel that cannot collide with Better Auth's 21-char nanoid IDs.
• Disabled in production. 404 when VERCEL_ENV=production. Vercel previews stay enabled.
• Disabled without secret. 404 when TEST_AUTH_SECRET is unset or shorter than 64 hex chars.
• Constant-time secret comparison via crypto.timingSafeEqual.
• Short session TTL (1 hour).
• Logged on every successful mint.

The bot is given a @vercel.com email so it bypasses the managed-template-trial gate (which otherwise caps at 1 session and 5 messages per non-Vercel user).

Verification

End-to-end verified against the live dev server:

1. Mint cookie via /api/dev/session → Better Auth's verifier accepts it (GET /api/auth/info returns the bot user).
2. Create a chat session via /api/sessions → real Vercel sandbox provisions in ~10s.
3. POST /api/chat streams a real agent response.
4. Follow-up turn referencing the same session has full prior context — agent recalled an 8-digit random number across turns.

Test plan

• Set TEST_AUTH_SECRET=$(openssl rand -hex 32) in apps/web/.env.local
• Run bash scripts/test-agent.sh — expect the agent to reply
• Run the printed follow-up command — expect the agent to have prior context
• Try without the secret header — expect 401
• Try without TEST_AUTH_SECRET set — expect 404
• Confirm production deploy still 404s the endpoint (env-gated)

🤖 Generated with Claude Code