feat: Planner Agent — auto-expand short prompts into full product specs

[ryaneggz]

Summary

Introduce a Planner Agent pre-execution phase to Orchestra's assistant pipeline. When enabled via PlannerConfig on an Assistant, the planner intercepts the first message in a thread, expands the user's short prompt (1-4 sentences) into a structured product specification, and optionally pauses for human-in-the-loop approval before the generator begins work.

This follows Anthropic's harness research showing that a high-level planning phase dramatically improves the ambition and coherence of generated output.

Key Capabilities

• PlannerConfig on the Assistant schema (toggleable enabled, auto_approve, model override, scope_level)
• Planner runs as a pre-phase before the generator on the first message of a thread
• Expands short prompts into structured product specs (Overview, Features, User Stories, Tech Stack, Design Direction)
• Persists plan as /PLAN.md in StateBackend for the generator to reference throughout execution
• Optional HITL approval — pause for user review before generator proceeds
• Planner prompted to be ambitious about scope and identify AI feature opportunities

Spec

Full spec: .claude/specs/planner-agent.md

Implementation Plan

Detailed plan: .claude/plans/planner-agent.md

Phases

1. Schema & Data Layer — PlannerConfig model, Assistant schema extension, Alembic migration
2. Planner System Prompt — High-level expansion prompt at backend/src/static/prompts/md/planner.md
3. Pre-Execution Phase — LLMController integration, HITL interrupt, StateBackend persistence
4. Frontend Display — Collapsible PlanPanel, approval UI, status indicators
5. Tests & Example — Unit + integration tests, example notebook

File Changes

File	Change
backend/src/schemas/entities/planner.py	New — PlannerConfig model
backend/src/schemas/entities/llm.py	Modify — add planner field to Assistant
backend/src/controllers/llm.py	Modify — pre-execution planner phase
backend/src/static/prompts/md/planner.md	New — planner system prompt
backend/migrations/versions/xxx_add_planner.py	New — Alembic migration
frontend/src/components/chat/PlanPanel.tsx	New — plan display component
examples/agents/planner_example.ipynb	New — example notebook

[ryaneggz]

Backend Implementation Analysis

1. Architecture Decision: Pre-Phase in LLMController (Recommended)

After studying construct_agent, init_graph, Orchestra, LLMController, the middleware stack, and the HITL infrastructure, the planner should be implemented as a pre-execution phase inside LLMController — not as middleware or a subagent. Here is why:

Approach	Verdict	Rationale
Middleware (@wrap_model_call)	Not suitable	Middleware runs on every model call within the agent loop (compaction, retry, PII, cache metrics). The planner needs to run once before the agent graph is even constructed, and it needs access to service_context, checkpointer, and thread state — none of which are available in the middleware ModelRequest interface.
Subagent	Not suitable	Subagents are initialized via init_subagents() and wired into the deepagents graph as peer nodes. The planner must complete and persist its output before the generator graph starts streaming. A subagent would run inside the graph, creating ordering and state-passing complications.
Pre-phase in LLMController	Best fit	Both llm_invoke() and llm_stream() (via stream_generator()) already have a clear sequential flow: resolve settings → load memories → resolve files → construct agent → invoke/stream. The planner slots in naturally between file resolution and agent construction. It has access to service_context, checkpointer, store, and the full LLMRequest — everything it needs.

The implementation point is clear: in LLMController.llm_invoke() between lines 130-137 (after resolve_context_files and before get_checkpoint_db), and equivalently in stream_generator() between lines 355-365 (after resolve_context_files and before the get_checkpoint_db block). Both paths need the same planner logic, so it should be extracted into a shared helper (e.g., run_planner_phase()).

---

2. Plan Injection: Via files (StateBackend /PLAN.md)

The architecture strongly favors persisting the plan as /PLAN.md in the files map, which flows into the StateBackend:

• params.input.files is already merged from memory files, persisted settings files, and explicit files via resolve_context_files() (see backend/src/services/context_files.py).
• The create_file_data() utility from deepagents.backends.utils is already used throughout the codebase to create file entries (see prepare_memory_files(), McpSandboxBackend, memory routes).
• Files in the StateBackend are automatically available to the agent's filesystem tools (read_file, write_file, etc.) and persist across the thread lifecycle via _persist_final_state() / _update_store().

Implementation:

from deepagents.backends.utils import create_file_data

# After planner produces plan_content:
params.input.files["/PLAN.md"] = create_file_data(plan_content)

This is simpler and more robust than system prompt injection (which would bloat the prompt and reduce cache hit rates given the init_system_prompt() caching structure), and more natural than the memory parameter (which is specifically for MemoryMiddleware file references).

---

3. HITL Integration: Existing Infrastructure Covers 90%, One Gap

What maps cleanly:

• add_human_in_the_loop() in backend/src/utils/tools.py wraps tools with interrupt() from langgraph.types, creating HumanInterrupt payloads with action_request, config, and description.
• CheckpointService.get_interrupts() parses interrupt state from the checkpoint and returns InterruptInfo objects.
• CheckpointService.resume_with_decision() handles accept/edit/response/reject decisions via Command(resume=...).
• The thread routes (GET /threads/{thread_id}/interrupts, POST /threads/{thread_id}/resume) expose the full HITL flow to the frontend.

The gap: The existing HITL flow is designed for tool-level interrupts — it wraps individual tool calls and pauses mid-execution inside the agent graph. The planner interrupt is different: it happens before the agent graph is constructed. This means:

• The planner cannot use interrupt() from inside the graph because no graph exists yet.
• Instead, the planner pre-phase should: (a) invoke a lightweight planner LLM call directly (outside the graph), (b) if auto_approve=False, persist the plan + interrupt metadata to the thread store and return early with an interrupt-like response, (c) the frontend shows the plan for approval, (d) on resume (via existing /threads/{thread_id}/resume or a new endpoint), the controller re-enters the flow, injects /PLAN.md into files, and proceeds to construct the generator agent.

Alternative approach (cleaner): Run the planner as its own mini-graph with a single tool that calls interrupt() to present the plan. This keeps the interrupt mechanism unified — the existing HITL endpoints would work without modification. The mini-graph would be constructed, invoked, and its checkpoint state would be part of the thread's checkpoint history. On resume, the controller detects the approved plan in the checkpoint state and proceeds.

I recommend the mini-graph approach because it reuses 100% of the existing HITL infrastructure with zero new endpoints.

---

4. First-Message Detection: Thread Emptiness Check Needed

The spec says: "Planner runs on the first message of a thread." But the codebase has no existing mechanism to detect whether a thread is new or has prior messages.

The controller currently gets params.metadata.thread_id which may be a new UUID (new thread) or an existing ID (continuation). To detect first-message:

Option A — Check checkpoint existence:

async with get_checkpoint_db() as checkpointer:
    config = RunnableConfig(configurable={"thread_id": thread_id})
    existing = await checkpointer.aget(config)
    is_first_message = existing is None

Option B — Check thread store:

thread = await service_context.thread_service.get(thread_id)
is_first_message = thread is None or not thread.messages

Option B is simpler and already used in the thread routes. Combined with checking assistant.planner.enabled, the guard becomes:

if assistant.planner and assistant.planner.enabled and is_first_message:
    plan = await run_planner_phase(...)

---

5. Re-Planning Mid-Thread: Not Covered, Should Be Deferred

The spec and plan mention re-planning as a risk mitigation ("allow re-planning via user command or after N messages") but do not specify it. The architecture supports it naturally:

• A user could send a message like "re-plan based on new requirements" and the planner phase could be triggered again.
• The /PLAN.md file in StateBackend can be overwritten at any time via create_file_data().
• However, implementing this in v1 adds complexity (detecting re-plan intent, merging with existing progress, etc.).

Recommendation: Defer re-planning to a follow-up issue. V1 should focus on first-message planning only.

---

6. Schema Integration Notes

The Assistant model in backend/src/schemas/entities/llm.py currently has no planner field. Adding it:

from src.schemas.entities.planner import PlannerConfig

class Assistant(BaseModel):
    # ... existing fields ...
    planner: Optional[PlannerConfig] = Field(default=None, description="Planner configuration")

Since assistants are stored in the LangGraph BaseStore (not a SQL table), no Alembic migration is needed — the JSONB storage handles schema evolution natively. Existing assistants will simply have planner=None.

The LLMService.assistant() method in backend/src/services/llm.py already converts assistants to LLMRequest via assistant.to_llm_request(). The planner config needs to be propagated through this path — either by adding planner to LLMRequest or by attaching it to the metadata.

---

7. Dual-Path Consistency (invoke vs. stream)

Both LLMController.llm_invoke() and stream_generator() need the planner phase. The duplicated structure between these two paths (visible in sandbox fallback logic) is already a maintenance burden. The planner should be extracted as:

async def run_planner_phase(
    params: LLMRequest,
    service_context: ServiceContext,
    files_map: dict,
    checkpointer: BaseCheckpointSaver,
) -> dict:
    """Run planner if enabled and first message. Returns updated files_map."""

This function would be called from both llm_invoke() and stream_generator() before agent construction.

---

Summary of Recommended Approach

1. PlannerConfig schema in backend/src/schemas/entities/planner.py — enabled, auto_approve, model, scope_level
2. Extend Assistant with planner: Optional[PlannerConfig]
3. Planner system prompt at backend/src/static/prompts/md/planner.md
4. Pre-phase helper run_planner_phase() — detects first message, invokes planner LLM, persists /PLAN.md via create_file_data() into files map
5. HITL approval via mini-graph with interrupt() — reuses existing /threads/{thread_id}/interrupts + /resume endpoints
6. Integration in both LLMController.llm_invoke() and stream_generator() — called after resolve_context_files() and before agent construction
7. No migration needed — assistants use JSONB store, not SQL columns
8. Defer re-planning to a follow-up issue

[ryaneggz]

Dependency Graph Validation

Position in Dependency Graph

Planner Agent (#898) — INDEPENDENT (Layer 0)
  └─ depended upon by: Harness Templates (#910), Sprint Contracts (#906)
  └─ soft dep from: Context Reset (#904), Social Media Campaign (#902)

Declared Dependencies

• None declared — claims to be independent.

Validated Dependencies

Correct. Planner Agent is genuinely independent. It introduces:

• PlannerConfig schema (new file planner.py)
• planner field on Assistant schema in llm.py
• Pre-execution phase in LLMController
• HITL integration for auto_approve=False (uses existing InterruptConfig/HumanDecision schemas — verified present)

Implicit Dependencies Found

1. HITL System — The spec relies on the existing HITL interrupt system (InterruptConfig, HumanDecision, ResumeRequest in hitl.py). This is already shipped and verified, so this is a satisfied implicit dependency.
2. StateBackend — Spec references persisting /PLAN.md in "StateBackend" but the codebase has no class called StateBackend. The closest concept is the files dict on Assistant and thread state. This terminology mismatch should be clarified — are plans persisted to assistant.files, thread checkpoint state, or a new storage layer?

Interface Contracts Needed

1. PlannerConfig schema — should be defined NOW so Harness Templates (feat: Sprint contracts — agents negotiate scope and pass/fail criteria before execution #910) and Context Reset (feat: Agent phase observability — structured traces with frontend timeline #904) can reference it. The spec proposes:

   class PlannerConfig(BaseModel):
       enabled: bool = False
       auto_approve: bool = True
       model: Optional[str] = None
       scope_level: Literal["conservative", "ambitious"] = "ambitious"

2. Assistant.planner field type — Optional[PlannerConfig] on the existing Assistant model. This is a schema migration that Harness Templates (feat: Sprint contracts — agents negotiate scope and pass/fail criteria before execution #910) depends on.

Schema Conflict Risk

• Medium. This spec and Evaluator (feat: Evaluator Agent — GAN-inspired generator/evaluator feedback loop #899) both modify llm.py:Assistant (adding planner and evaluator fields respectively). If built in parallel, Alembic migrations will conflict. Recommendation: Coordinate migration ordering or combine into a single migration.

Critical Path Assessment

On critical path. Harness Templates (#910) and Sprint Contracts (#906) are blocked without this. Should be built in Wave 1 alongside Evaluator (#899).

[ryaneggz]

Migration Strategy Note

Schema Changes Required

• PlannerConfig is a new nested Pydantic model added as an optional field on Assistant.
• Since Assistants are stored in LangGraph Store (schemaless JSON document store, not a SQL table), adding the planner: Optional[PlannerConfig] field to the Assistant Pydantic model requires NO Alembic migration. The LangGraph Store is schema-on-read; existing assistants without a planner field will simply default to None.

Migration Needs

• None. Zero new SQL tables, zero column additions. The plan file (/PLAN.md) is persisted to StateBackend (LangGraph graph state files), not a SQL table.

Parallel Development Safety

• This feature is safe to develop on a separate branch with no migration conflict risk since it touches zero Alembic files.
• The only schema concern is the Assistant Pydantic model in backend/src/schemas/entities/llm.py -- if another feature branch also modifies this file (e.g., feat: Evaluator Agent — GAN-inspired generator/evaluator feedback loop #899 evaluator, feat: Context reset with structured handoff artifacts for long-running sessions #906 context_strategy), there will be a merge conflict in the Python file, but NOT a migration conflict. Standard code merge resolution applies.

Recommendation

• Implement PlannerConfig as a Pydantic model in backend/src/schemas/entities/planner.py.
• Add planner: Optional[PlannerConfig] = None to Assistant in llm.py.
• No migration file needed. This can land independently of all other specs.

[ryaneggz]

Testing Strategy Recommendations

Infrastructure Observations

Orchestra's test suite uses: pytest + pytest-asyncio for backend (unit in tests/unit/, integration in tests/integration/), Vitest + Testing Library for frontend, respx for HTTP mocking, fakeredis for Redis, and InMemoryStore for LangGraph store. The conftest.py provides async_client (ASGI test client with dependency overrides), test_db, test_store, fake_redis, and an autouse mock for all external API calls (OpenAI, Anthropic, Airtable).

Recommended Tests for Planner Agent

Unit Tests (tests/unit/schemas/test_planner_config.py)

• PlannerConfig Pydantic validation: defaults (enabled=False, auto_approve=True, scope_level="ambitious"), invalid scope_level values rejected, optional model field
• Assistant schema accepts optional planner: PlannerConfig field, backward compat when field is absent

Unit Tests (tests/unit/controllers/test_planner_phase.py)

• Planner phase triggers ONLY on the first message of a thread (check thread_id state / message count)
• Planner phase is skipped when planner.enabled=False
• Planner respects model override — verify init_chat_model is called with planner's model, not generator's
• When auto_approve=False, HITL interrupt is created with plan content (mock graph, verify Command with interrupt)
• When auto_approve=True, no interrupt is created, plan is persisted directly
• Plan content is persisted to StateBackend as /PLAN.md (mock StateBackend, verify aput call)

Key Mock Strategy: The planner LLM call can be fully mocked — use the existing respx pattern or unittest.mock.patch("src.controllers.llm.init_chat_model") returning a mock that yields structured markdown. No real LLM calls needed.

Integration Test (tests/integration/test_planner_flow.py)

• End-to-end via async_client: POST /api/llm/stream with an assistant that has planner enabled → verify SSE stream contains planning status events before generator output
• Verify plan shows up in thread state after completion (GET thread state)

Frontend Tests

• PlanPanel.tsx component test: renders collapsed by default, expands on click, shows plan markdown
• HITL approval UI: renders approve/reject buttons when auto_approve=False, calls correct API on click

Gaps in Spec's Test Section

• Missing: Test for re-planning (spec mentions "allow re-planning via user command or after N messages" but no tests specified)
• Missing: Test that planner does NOT run on subsequent messages in the same thread
• Missing: Negative test for planner producing empty/invalid output — how does the system handle it?
• Missing: Test that /PLAN.md is included in generator's memory/context files

Shared Fixtures Needed

• planner_assistant_fixture: an Assistant dict with planner: PlannerConfig(enabled=True) pre-configured
• mock_plan_output: a realistic structured markdown plan to use across planner tests

[ryaneggz]

Downstream Dependency: Sprint Contracts (#910) Requirements

Sprint Contracts (#910) is a soft downstream dependency of the Planner. While contracts can function without a planner, the specs describe the planner's output as the high-level input that contracts decompose into testable sprints. Here are the specific interface gaps.

What Sprint Contracts Needs from the Planner

1. Structured Output Format (Not Just Free-Form Markdown)

The planner spec outputs /PLAN.md as free-form structured markdown (Overview, Features, User Stories, Tech Stack, Design Direction). Sprint Contracts needs to consume this programmatically to generate sprint proposals with testable criteria.

Gap: There is no machine-parseable structure in the planner's output. The generator agent would need to re-read and interpret the markdown to decompose it into sprints — essentially re-planning.

Recommendation: Add an optional structured output section to the planner's /PLAN.md that Sprint Contracts can parse:

## Features
### Feature 1: User Authentication
- **Priority:** high
- **Complexity:** medium  
- **User Stories:**
  - As a user, I can register with email and password
  - As a user, I can log in and receive a session token

Or persist a parallel /PLAN.json with structured feature data alongside the human-readable /PLAN.md. This way the planner's output can be consumed by both humans (markdown) and Sprint Contracts (structured data).

2. Sprint Decomposition Capability

The sprint-contracts spec says contracts "break down" the planner's high-level spec into sprint-sized chunks. But the planner currently has no concept of sprints or work chunking — it outputs a single monolithic spec.

Two options:

1. Planner does the chunking: Add a sprint_decomposition: bool flag to PlannerConfig. When enabled, the planner groups features into recommended sprints (Sprint 1: core auth, Sprint 2: dashboard, etc.). This gives Sprint Contracts a starting point for proposals.

2. Generator does the chunking: The generator reads /PLAN.md and decides how to chunk work into sprints. This is simpler but means the planner and Sprint Contracts have no direct interface.

Recommendation: Option 1 is better for the overall harness design. The planner is the right place to make scope decisions, and sprint-level decomposition is a natural extension of spec expansion.

3. Feature Priority and Complexity Metadata

Sprint Contracts needs to decide which features go in which sprint. The planner is the natural source for priority and complexity estimates, but the current spec doesn't include these.

Recommendation: When sprint_decomposition is enabled, the planner should annotate each feature with:

• priority: Literal["high", "medium", "low"]
• estimated_complexity: Literal["small", "medium", "large"]

These directly inform sprint contract scope — high-priority features go in earlier sprints, and complexity estimates help size sprint contracts appropriately.

Impact on Implementation Order

The Planner's Phase 2 (System Prompt) is the most relevant touch point. The system prompt should instruct the planner to output features in a structured, enumerated format — even without the sprint_decomposition flag — so that downstream consumers can parse individual features reliably.

Phase 1 (Schema) should reserve space for sprint_decomposition in PlannerConfig even if not implemented immediately, to avoid a schema migration later.

Summary

Gap	Severity	Recommendation
No structured output format for features	Medium	Add structured section to /PLAN.md or parallel /PLAN.json
No sprint decomposition capability	Medium	Add sprint_decomposition flag to PlannerConfig
No priority/complexity metadata on features	Low	Add annotations when sprint decomposition is enabled

These are soft requirements — Sprint Contracts CAN work without them by having the generator interpret the plan markdown. But addressing them makes the Planner → Sprint Contracts pipeline significantly more reliable and reduces prompt-engineering burden on the generator.

[ryaneggz]

Model Selection & Override Analysis

Research into how model selection currently works in Orchestra and what it means for the Planner Agent's PlannerConfig.model override field.

Current Model Selection Flow

1. User selects model via the frontend dropdown or API LLMRequest.model field.
2. LLMController._resolve_user_settings() resolves the final model string:
   • If the request has no model, falls back to user's default_model from UserSettingsRepo.
   • If still none, uses DEFAULT_CHAT_MODEL (system-level default).
3. API key routing: resolve_api_key(model, user_keys) in backend/src/utils/llm.py extracts the provider prefix (e.g., openai:, anthropic:, google_genai:) and looks up the matching API key — first from user-stored keys, then from system env vars.
4. init_graph() in backend/src/agents/__init__.py calls init_chat_model(model, api_key=api_key) to produce a BaseChatModel instance. This single API key is passed only to the main agent's model.
5. The Orchestra class stores the model and passes it to init_graph() which creates the deep agent via create_deep_agent(model=llm, ...).

Subagent Model Override (Already Works)

The deepagents library already supports per-subagent model overrides:

• SubAgent TypedDict has an optional model field: model: NotRequired[str | BaseChatModel]
• In create_deep_agent(), each subagent's model is resolved via subagent_model = spec.get("model", model) then resolve_model(subagent_model).
• resolve_model() calls init_chat_model(model_string) which picks up API keys from environment variables (not from the explicit api_key parameter passed to the main model).
• Orchestra's init_subagents() already conditionally sets subagent_dict["model"] = subagent.model when the subagent has a model override.

This means: subagent model overrides already work, but they rely on system-level env vars for API keys, not user-provided keys.

Can the Planner Use a Different Model Than the Generator?

Yes, architecturally this is fully feasible. The planner runs as a separate pre-execution LLM call (per the spec), not as a subagent within the same graph. The planner would:

1. Call init_chat_model(planner_model) independently.
2. Invoke the planner LLM to produce /PLAN.md.
3. Then proceed to the generator with the original user model.

Since the planner is a separate ainvoke() call in the controller layer (Step 4 of the spec), it naturally supports a different model. The generator and planner never share the same BaseChatModel instance.

API Key Routing Gap

This is the main concern. Currently, API key resolution happens once in _resolve_user_settings() and is tied to the generator's model. If the planner uses a different provider (e.g., planner = anthropic:claude-opus-4-1, generator = openai:gpt-5):

• The api_key resolved for the generator won't work for the planner.
• The planner will need its own resolve_api_key(planner_model, user_keys) call.
• System-level env vars will work fine (each provider's key is separate: ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.).
• User-provided keys: The planner must independently call resolve_api_key() with the planner model and the user's decrypted keys.

Recommendation: In the planner pre-execution phase in LLMController, resolve API keys separately:

planner_model = planner_config.model or params.model  # fall back to generator model
planner_api_key = resolve_api_key(planner_model, user_keys)

Does init_chat_model Support Multiple Calls?

Yes. init_chat_model() is a pure factory function — it creates a new BaseChatModel instance each time. It has no global state. The codebase already calls it in multiple places:

• init_graph() for the main agent model
• dynamic_model_selection middleware (swaps model mid-request)
• SummarizationMiddleware.compact() for the compaction model
• resolve_model() inside deepagents for subagent models

Multiple concurrent calls with different models are safe.

Model Availability Validation Gap

The spec does not account for validating that the planner model is available. Current gaps:

1. No validation at config time: When a user sets PlannerConfig.model = "anthropic:claude-opus-4-1", nothing checks whether the ANTHROPIC_API_KEY exists or the model is in the get_all_models() list.
2. Runtime failure: If the planner model's provider has no API key, init_chat_model() will succeed (it's lazy) but the ainvoke() call will fail with an auth error, blocking the entire request.
3. Existing pattern: The ChatModels enum conditionally defines models based on available API keys (if ANTHROPIC_API_KEY: ...), but this is a system-level check. User-level key availability isn't validated until the actual LLM call.

Recommendation: Add validation in the planner pre-execution phase:

if planner_config.model:
    planner_api_key = resolve_api_key(planner_config.model, user_keys)
    if not planner_api_key:
        # Fall back to generator model or skip planning
        logger.warning(f"Planner model {planner_config.model} has no API key, falling back to generator model")
        planner_model = params.model
        planner_api_key = api_key

Summary of Gaps to Address

Gap	Severity	Recommendation
API key must be resolved separately for planner model	High	Call resolve_api_key(planner_model, user_keys) independently
No model availability validation in PlannerConfig	Medium	Validate API key exists before planner invocation, fall back to generator model
Planner latency not bounded	Low	Consider a timeout or using DEFAULT_CHAT_MODEL_BASIC as planner default
User-provided keys for cross-provider planner/generator	Medium	Both user keys and system keys must be checked for the planner's provider

[ryaneggz]

SSE Streaming Design — Planning Status

Context

The Planner Agent runs as a pre-execution phase on the first message of a thread. It expands the user's short prompt into a structured product spec and optionally pauses for HITL approval. The frontend needs to display: "Planning...", the generated plan content as it streams, and "Awaiting approval" when HITL is active.

Recommended Approach

Use "custom" stream mode with "plan_status" sub-type. Same mechanism as cost (#905) and evaluation (#899).

Backend — emit planner phase events:

# Phase 1: Planner starts
stream_writer(("custom", {
    "type": "plan_status",
    "data": {
        "status": "planning",       # "planning" | "awaiting_approval" | "approved" | "rejected" | "generating"
        "plan_preview": None,       # null until plan is ready
    }
}))

# Phase 2: Plan complete, awaiting HITL approval
stream_writer(("custom", {
    "type": "plan_status",
    "data": {
        "status": "awaiting_approval",
        "plan_preview": "## Overview\nA full-stack...",  # markdown content
        "plan_file": "/PLAN.md",
    }
}))

# Phase 3: After approval, generator begins
stream_writer(("custom", {
    "type": "plan_status",
    "data": {
        "status": "generating",
        "plan_preview": "## Overview\nA full-stack...",
    }
}))

Interaction with existing HITL interrupts:

The planner's HITL approval should use LangGraph's existing interrupt mechanism. When the graph hits an interrupt:

1. The backend emits ("custom", {"type": "plan_status", "data": {"status": "awaiting_approval", ...}}) right before the interrupt
2. The stream pauses (LangGraph stops yielding chunks)
3. The frontend renders the PlanPanel with approve/reject buttons
4. User approval sends a resume API call; the graph resumes and emits status: "approved" then continues to the generator

Frontend consumption:

1. Handle custom events where payload.type === "plan_status" in useChat.ts
2. Store in a planState: { status, planPreview, planFile }
3. PlanPanel.tsx reads this state and renders:
   • "Planning..." spinner during planning
   • Collapsible markdown preview with approve/reject during awaiting_approval
   • "Plan approved, generating..." indicator during generating
4. For "planning" status, also update setLoadingMessage("Planning...") so the existing loading indicator reflects the phase

Plan content streaming: The plan markdown can stream incrementally via standard "messages" mode chunks (it's just AI text output). The "plan_status" custom event carries only the phase status and the final plan summary, not the token-by-token content.

Distributed mode: Works automatically via existing Redis stream passthrough.