feat(ai-agent): multi-turn design agent - clarify, plan, then generate

[Suharshit]

Stacked on #22 (which is stacked on #21). The base is feat/ai-sessions-wiring, so this diff shows step 3 only. Merge in order #21 → #22 → this, re-targeting each PR's base to main as the one below it merges.

Why

The design agent turned a single prompt straight into a diagram, so vague prompts produced guesswork and there was no chance to agree on the architecture first. This is step 3 of the AI sessions plan: a short conversation (clarify → plan → generate) on top of the stored sessions from #21 and #22.

What

• Turn engine: each turn is still one design-agent run. The agent:
  • keeps a running requirements brief on the session
  • asks clarifying questions when an unknown would change the architecture: at most 3 per round, each with suggested answers, for up to 3 rounds
  • proposes a plan: summary, components with roles, key flows, major decisions with rationale and alternatives, and assumptions
  • draws the diagram only once the plan is approved; asking for a change revises the plan
• Rules enforced in code (enforceDecision): no questions after a skip or past 3 rounds, no generating without a plan, no "ask" with zero questions.
• Turns route: accepts message, answers (only while questions are open), generate (409 without a plan) and skip.
  • Replies are saved as QUESTIONS, PLAN or RESULT from run output validated with zod. RESULT carries the plan's decisions, which the spec feature can reuse later.
  • A failed turn leaves the session's phase unchanged.
• Sidebar: only progress labels changed. The composer still sends plain messages, so for now users answer and approve by typing ("looks good, draw it"). Question and plan cards with buttons come in step 4.

Hardening found while testing

• Latency: default thinking took 34–82s per call. Thinking is now set per step: thinkingLevel on Gemini 3, thinkingBudget on Gemini 2.x. Calls took 4–30s after that.
• Intermittent "response did not match schema": the model fills lists up to their limits, and Gemini doesn't reliably enforce maxItems.
  • List limits are now stated in the schema descriptions and trimmed in code.
  • Each structured call retries once on a schema mismatch.
  • The same applies to diagram nodes (24) and edges (48).
• A model request held open for 5+ minutes under load:
  • every call now has a timeout (analyze 90s, plan 150s, generate 120s)
  • the task has maxDuration: 300
  • the task makes a single attempt, since turn-level retries multiplied quota use and could draw a diagram twice
• Raw provider errors reached the chat: run failures are now stored as friendly messages (usage limit, busy, timeout, generic), and the raw error goes to the server log.

Verification

• pnpm typecheck and pnpm lint pass.
• Engine eval against Gemini (3.5-flash, then 2.5-flash):
  • a vague prompt got 3 relevant questions with options; answers led to a plan with no repeated questions
  • a detailed URL-shortener prompt went straight to a plan with 13 components and 5 decisions, which validates
  • the drawn graph used exactly the plan's 8 components
  • "add a Redis cache" revised the plan, kept every component and added a cache
  • skip produced a plan with stated assumptions
  • "looks good, draw it" chose generate; "looks good, but use Postgres" chose to revise
• Offline checks (15): over-long questions, briefs, plans and graphs are trimmed rather than rejected; empty plans and graphs are still rejected; no edge points at a trimmed node.
• Database turn checks (15): pass with the new input types.
• Through the local Trigger worker:
  • first message → 3 questions
  • answers stored paired with their questions → second round of questions, with round count, phase and brief correct
  • the 409 guards
  • the friendly usage-limit message
  • the 90s timeout failing a turn cleanly

End-to-end run (verified)

The full flow through the local Trigger worker passed on gemini-3.5-flash-lite (the free-tier quotas for 3.5-flash and 2.5-flash were used up, and gemini-3-flash-preview was overloaded):

• First message: "I want to build a marketplace app" got 3 clarifying questions in 15.8s.
• Skip: a plan in 12.3s with 9 components, 4 flows, 3 decisions and assumptions. Phase PLANNED; the brief was stored and the plan payload is valid.
• Answers after the plan: refused with 409.
• Generate: "Added 9 components and 8 connections to the canvas." in 12.6s. The result carries the plan's decisions and the phase is COMPLETE.

The test project, Liveblocks room, sessions and TaskRuns were removed afterwards.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
draftly	Ready	Preview	Sep 15, 2026 6:45pm UTC

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 3ef62fb6-1cf2-44c7-ae8b-a203dd73625a

---

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.}