feat(backend): planner-selected model profile routing with fail-open fallback

[jbax1899]

Adds planner profile selection for chat responses by introducing profileId in planner output and PLANNER_PROFILE_ID for planner execution.
The orchestrator now runs planner and response on separate profiles, validates planner-selected profile IDs against enabled catalog entries, and fails open to DEFAULT_PROFILE_ID on invalid/disabled selections.
Also adds bounded profile context to the planner prompt and no-op runtime seam prep (GenerationRequest.userId?, GenerationResult.memoryRetrievals?) with no behavioral change outside profile routing.
Intentionally deferred: Search-capability reroute policy (currently degrade by dropping search when selected profile can’t search).

Summary by CodeRabbit

• New Features

  • Planner and response generation can use separate model profiles; planners may request a profile for execution.

• Configuration

  • New PLANNER_PROFILE_ID environment variable to set the planner’s model profile (defaults to openai-text-fast).

• Improvements

  • Workflow: changed default local linting to auto-fix and added changed-file-aware formatting scripts.

• Documentation & Tests

  • Updated testing/validation guidance and added tests covering planner-driven profile selection and search behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6ecf9502-fbbe-4ba6-96f5-328ca9d84901

📥 Commits

Reviewing files that changed from the base of the PR and between 603be37 and 7a6e94d.

📒 Files selected for processing (2)

• packages/prompts/src/defaults.yaml
• scripts/format-changed.cjs

✅ Files skipped from review due to trivial changes (1)

• scripts/format-changed.cjs

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/prompts/src/defaults.yaml

---

📝 Walkthrough

Walkthrough

Adds a planner-specific model profile (PLANNER_PROFILE_ID) and propagates planner-chosen profile IDs through planner and orchestrator logic, updates config/types, prompts schema, tests, and developer tooling/scripts for changed-file formatting and lint workflows.

Changes

Cohort / File(s)	Summary
Env examples & spec \.env.example, packages/config-spec/src/env-spec.ts	Added PLANNER_PROFILE_ID env entry (default openai-text-fast) and updated .env.example comment to clarify planner vs response profile usage.
Backend config & types packages/backend/src/config/sections/modelProfiles.ts, packages/backend/src/config/types.ts	Parse PLANNER_PROFILE_ID into runtime config; added plannerProfileId: string to RuntimeConfig['modelProfiles'].
Planner outputs & options packages/backend/src/services/chatPlanner.ts, packages/prompts/src/defaults.yaml	Planner JSON schema now includes profileId; ChatPlan gains optional profileId; added ChatPlannerProfileOption type and availableProfiles injection into planner prompt context.
Orchestrator runtime selection packages/backend/src/services/chatOrchestrator.ts	Orchestrator computes plannerProfile and defaultResponseProfile, passes availableProfiles to planner, normalizes/validates planner profileId, falls back with warnings, creates executionPlan and strips unsupported features (e.g., search) based on selected profile capabilities.
Agent runtime types packages/agent-runtime/src/index.ts	Added optional userId?: string to GenerationRequest and memoryRetrievals?: [] to GenerationResult.
Tests packages/backend/test/... (chatOrchestrator.test.ts, chatPlanner.test.ts, chatService.test.ts, modelProfileCatalog.test.ts)	Expanded/added tests for planner-selected profileId parsing/normalization, valid/invalid profile resolution and warnings, dropping unsupported search, and memoryRetrievals tolerance. Minor formatting updates.
Dev workflow & linting AGENTS.md, cursor.rules, package.json, scripts/format-changed.cjs	Switched default post-edit step to pnpm lint:fix and added pnpm lint for non-mutating CI checks; added format:check/format:write scripts backed by scripts/format-changed.cjs; updated PR readiness gate to require pnpm review and docker compose ... build.
Format helper scripts/format-changed.cjs	New script to run Prettier against changed files (supports --write and FORMAT_BASE_REF).

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Orchestrator
    participant ModelCatalog
    participant Planner
    participant PlannerRuntime as Planner Runtime
    participant ResponseRuntime as Response Runtime

    Client->>Orchestrator: Send chat request
    Orchestrator->>ModelCatalog: Load enabledProfiles + plannerProfileId + defaultResponseProfile
    Orchestrator->>Planner: Send request + availableProfiles (plannerProfile used)
    Planner->>PlannerRuntime: Generate plan (uses plannerProfile provider/model)
    PlannerRuntime-->>Planner: Return plan (may include profileId)
    Planner-->>Orchestrator: Normalized plan (action, profileId)
    Orchestrator->>Orchestrator: Resolve plan.profileId vs enabledProfiles
    alt profileId valid
        Orchestrator->>Orchestrator: Use selected response profile
    else invalid/missing
        Orchestrator->>Orchestrator: Warn and fallback to defaultResponseProfile
    end
    Orchestrator->>Orchestrator: If selected profile lacks search -> remove search (warn)
    Orchestrator->>ResponseRuntime: Generate response using executionPlan + selected profile
    ResponseRuntime-->>Orchestrator: Return response
    Orchestrator-->>Client: Deliver final response

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• Enhance model profile handling in backend configuration and runtime. #197: Related work on model-profiles and planner-driven profile selection in orchestrator/planner code paths.
• Unify chat prompting and isolate VoltAgent logging #194: Earlier planner/orchestrator modifications that this PR extends with profile selection behavior.
• Standardize env parsing around package-level runtime config #178: Prior env-spec and model-profiles config work that this PR builds on by adding PLANNER_PROFILE_ID.

Suggested labels

enhancement

Poem

🐰 A rabbit peeks at config lines,
Planner fast, responder fine.
Profiles split their thoughtful art,
One to plan and one to part.
Hops of logic, neatly paired—hooray! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main feature being implemented: planner-selected model profile routing with a fail-open fallback mechanism. It directly reflects the changeset's primary objective of adding profile selection logic to the orchestrator and validation with fallback behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/planner-profile-selection

---

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 and usage tips.}