root/fusion

Fork 0

Files

gsxdsm dd58a3ec43 feat(FN-2119): merge fusion/fn-2119

2026-04-19 10:13:34 -07:00

26 KiB

Raw Blame History

Settings Reference

← Docs index

This guide documents Fusion settings from packages/core/src/types.ts.

Settings Scopes

Fusion uses a two-tier settings system:

Global settings (~/.fusion/settings.json): user preferences shared across projects
Project settings (.fusion/config.json): execution/runtime behavior for one project

At runtime, settings are merged. Project settings override global settings when keys overlap.

Settings API Endpoints

Endpoint	Purpose
`GET /api/settings`	Get merged settings (global + project).
`PUT /api/settings`	Update project settings only.
`GET /api/settings/global`	Get global settings only.
`PUT /api/settings/global`	Update global settings only.
`GET /api/settings/scopes`	Get separated `{ global, project }` view.

Global Settings

Defaults from DEFAULT_GLOBAL_SETTINGS; key scope from GLOBAL_SETTINGS_KEYS.

Setting	Type	Default	Description
`themeMode`	`"dark" \| "light" \| "system"`	`"dark"`	Dashboard theme mode.
`colorTheme`	`ColorTheme`	`"default"`	Dashboard color theme preset.
`defaultProvider`	`string`	`undefined`	Default AI provider.
`defaultModelId`	`string`	`undefined`	Default AI model ID.
`fallbackProvider`	`string`	`undefined`	Fallback provider when the primary default model hits transient provider failures.
`fallbackModelId`	`string`	`undefined`	Fallback model ID (must pair with `fallbackProvider`).
`defaultThinkingLevel`	`"off" \| "minimal" \| "low" \| "medium" \| "high"`	`undefined`	Default reasoning effort for AI sessions.
`ntfyEnabled`	`boolean`	`false`	Enable ntfy push notifications.
`ntfyTopic`	`string`	`undefined`	ntfy topic name.
`ntfyEvents`	`("in-review" \| "merged" \| "failed" \| "awaiting-approval" \| "awaiting-user-review")[]`	`["in-review","merged","failed","awaiting-approval","awaiting-user-review"]`	Event types that trigger ntfy notifications.
`ntfyDashboardHost`	`string`	`undefined`	Dashboard host used to build deep links in notifications.
`defaultProjectId`	`string`	`undefined`	Default project for multi-project CLI operations when `--project` is omitted.
`setupComplete`	`boolean`	`undefined`	Tracks completion of first-run setup.
`favoriteProviders`	`string[]`	`undefined`	Pinned providers shown first in model selectors.
`favoriteModels`	`string[]`	`undefined`	Pinned models in `{provider}/{modelId}` format.
`openrouterModelSync`	`boolean`	`true`	Sync OpenRouter model catalog into model pickers at startup.
`modelOnboardingComplete`	`boolean`	`undefined`	Whether AI onboarding has been completed or dismissed.
`executionGlobalProvider`	`string`	`undefined`	Global baseline provider for task execution. Project `executionProvider` overrides this.
`executionGlobalModelId`	`string`	`undefined`	Global baseline model ID for task execution.
`planningGlobalProvider`	`string`	`undefined`	Global baseline provider for planning/triage. Project `planningProvider` overrides this.
`planningGlobalModelId`	`string`	`undefined`	Global baseline model ID for planning/triage.
`validatorGlobalProvider`	`string`	`undefined`	Global baseline provider for validator/reviewer runs. Project `validatorProvider` overrides this.
`validatorGlobalModelId`	`string`	`undefined`	Global baseline model ID for validator/reviewer runs.
`titleSummarizerGlobalProvider`	`string`	`undefined`	Global baseline provider for title summarization. Project `titleSummarizerProvider` overrides this.
`titleSummarizerGlobalModelId`	`string`	`undefined`	Global baseline model ID for title summarization.
`daemonToken`	`string`	`undefined`	Daemon authentication token (`fn_<32 hex chars>`) used by CLI clients.
`daemonPort`	`number`	`4040`	Port for daemon/serve mode binding.
`daemonHost`	`string`	`"0.0.0.0"`	Host for daemon/serve mode binding.
`settingsSyncEnabled`	`boolean`	`false`	Enable automatic settings synchronization between nodes.
`settingsSyncAuth`	`boolean`	`false`	Include model auth credentials in settings sync operations.
`settingsSyncInterval`	`number`	`900000`	Automatic sync interval in ms. Valid values: `300000`, `900000`, `1800000`, `3600000`.
`settingsSyncConflictResolution`	`"last-write-wins" \| "always-ask" \| "keep-local" \| "keep-remote"`	`"last-write-wins"`	Conflict strategy for divergent synced settings.

Project Settings

Defaults from DEFAULT_PROJECT_SETTINGS; key scope from PROJECT_SETTINGS_KEYS.

Setting	Type	Default	Description
`globalPause`	`boolean`	`false`	Hard stop: terminate active engine sessions and pause scheduling immediately.
`globalPauseReason`	`string`	`undefined`	Optional reason for `globalPause` (`"rate-limit"` for automatic pauses, `"manual"` for user-triggered pauses). Cleared on unpause.
`enginePaused`	`boolean`	`false`	Soft pause: stop dispatching new work while letting active sessions finish.
`maxConcurrent`	`number`	`2`	Max concurrent task-lane AI agents (triage, executor, merge).
`maxTriageConcurrent`	`number`	`2`	Max concurrent triage/specification agents.
`globalMaxConcurrent`	`number`	`4`	System-wide max concurrent agents across all projects.
`maxWorktrees`	`number`	`4`	Max git worktrees.
`pollIntervalMs`	`number`	`15000`	Scheduler poll interval (ms).
`groupOverlappingFiles`	`boolean`	`true`	Serialize execution when file scopes overlap.
`autoMerge`	`boolean`	`true`	Auto-finalize tasks from `in-review`.
`mergeStrategy`	`"direct" \| "pull-request"`	`"direct"`	Completion mode (local direct merge vs PR-first).
`worktreeInitCommand`	`string`	`undefined`	Shell command run after worktree creation.
`testCommand`	`string`	`undefined`	Merge-time test command (hard gate). When unset, Fusion auto-detects from lockfile.
`buildCommand`	`string`	`undefined`	Merge-time build command (hard gate).
`recycleWorktrees`	`boolean`	`false`	Reuse worktrees from a pool for faster startup.
`worktreeNaming`	`"random" \| "task-id" \| "task-title"`	`"random"`	Naming mode for new worktree directories.
`taskPrefix`	`string`	`"FN"`	Prefix used for newly generated task IDs.
`includeTaskIdInCommit`	`boolean`	`true`	Include task ID as commit scope in generated commits.
`commitAuthorEnabled`	`boolean`	`true`	Apply explicit `--author` attribution on Fusion commits.
`commitAuthorName`	`string`	`"Fusion"`	Commit author name when `commitAuthorEnabled` is true.
`commitAuthorEmail`	`string`	`"noreply@runfusion.ai"`	Commit author email when `commitAuthorEnabled` is true.
`planningProvider`	`string`	`undefined`	Provider for planning/triage agents.
`planningModelId`	`string`	`undefined`	Model ID for planning/triage agents.
`planningFallbackProvider`	`string`	`undefined`	Fallback provider for planning/triage.
`planningFallbackModelId`	`string`	`undefined`	Fallback model ID for planning/triage.
`defaultProviderOverride`	`string`	`undefined`	Project-level override for global default provider baseline.
`defaultModelIdOverride`	`string`	`undefined`	Project-level override for global default model baseline.
`executionProvider`	`string`	`undefined`	Provider for task execution agents.
`executionModelId`	`string`	`undefined`	Model ID for task execution agents.
`validatorProvider`	`string`	`undefined`	Provider for plan/code reviewers.
`validatorModelId`	`string`	`undefined`	Model ID for plan/code reviewers.
`validatorFallbackProvider`	`string`	`undefined`	Fallback provider for reviewers.
`validatorFallbackModelId`	`string`	`undefined`	Fallback model ID for reviewers.
`modelPresets`	`ModelPreset[]`	`[]`	Reusable executor/validator model presets.
`autoSelectModelPreset`	`boolean`	`false`	Auto-select presets by task size.
`defaultPresetBySize`	`{ S?: string; M?: string; L?: string }`	`{}`	Mapping for `S`/`M`/`L` → preset ID.
`autoResolveConflicts`	`boolean`	`true`	Enable automatic merge conflict resolution.
`smartConflictResolution`	`boolean`	`true`	Alias/preferred flag for smart conflict handling.
`strictScopeEnforcement`	`boolean`	`false`	Block merges on out-of-scope file changes.
`buildRetryCount`	`number`	`0`	Build retry attempts during merge.
`verificationFixRetries`	`number`	`1`	Auto-fix retry attempts when verification fails during merge.
`buildTimeoutMs`	`number`	`300000`	Build timeout in milliseconds (5 minutes).
`requirePlanApproval`	`boolean`	`false`	Require manual approval before triage → todo.
`specStalenessEnabled`	`boolean`	`false`	Enforce automatic re-triage for stale specs.
`specStalenessMaxAgeMs`	`number`	`21600000`	Spec staleness threshold in ms (6 hours).
`taskStuckTimeoutMs`	`number`	`undefined`	Inactivity timeout for stuck-task recovery.
`aiSessionTtlMs`	`number`	`604800000`	TTL in ms for persisted planning/subtask/mission sessions (7 days).
`aiSessionCleanupIntervalMs`	`number`	`3600000`	Interval in ms for AI session cleanup sweeps (1 hour).
`autoUnpauseEnabled`	`boolean`	`true`	Auto-unpause after rate-limit-triggered pauses; manual pauses stay paused until explicitly unpaused by the user.
`autoUnpauseBaseDelayMs`	`number`	`300000`	Base unpause delay in ms (5 min).
`autoUnpauseMaxDelayMs`	`number`	`3600000`	Max auto-unpause delay in ms (1 hour).
`maxStuckKills`	`number`	`6`	Max stuck-task terminations before permanent failure.
`maxPostReviewFixes`	`number`	`1`	Max auto-revival attempts for in-review tasks failing pre-merge workflow steps.
`maxSpawnedAgentsPerParent`	`number`	`5`	Max child agents per parent task.
`maxSpawnedAgentsGlobal`	`number`	`20`	Max spawned agents across one executor instance.
`maintenanceIntervalMs`	`number`	`900000`	Periodic maintenance interval in ms (15 min).
`autoArchiveDoneTasksEnabled`	`boolean`	`true`	Enable periodic auto-archiving of done tasks.
`autoArchiveDoneAfterMs`	`number`	`172800000`	Age in ms after entering done before auto-archive (48h).
`archiveAgentLogMode`	`"none" \| "compact" \| "full"`	`"compact"`	Agent log retention strategy for cold archive snapshots.
`autoUpdatePrStatus`	`boolean`	`false`	Auto-refresh PR status badges.
`autoCreatePr`	`boolean`	`false`	Auto-create PRs for completed tasks.
`autoBackupEnabled`	`boolean`	`false`	Enable scheduled DB backups.
`autoBackupSchedule`	`string`	`"0 2 * * *"`	Backup cron schedule.
`autoBackupRetention`	`number`	`7`	Number of backups to retain.
`autoBackupDir`	`string`	`".fusion/backups"`	Relative backup directory path.
`autoSummarizeTitles`	`boolean`	`false`	Auto-generate titles for long untitled descriptions.
`titleSummarizerProvider`	`string`	`undefined`	Provider for title summarization.
`titleSummarizerModelId`	`string`	`undefined`	Model ID for title summarization.
`titleSummarizerFallbackProvider`	`string`	`undefined`	Fallback provider for title summarization.
`titleSummarizerFallbackModelId`	`string`	`undefined`	Fallback model ID for title summarization.
`scripts`	`Record<string, string>`	`undefined`	Named script map used by script-mode workflow steps and setup hooks.
`setupScript`	`string`	`undefined`	Script key from `scripts` to run before task execution.
`insightExtractionEnabled`	`boolean`	`false`	Enable scheduled memory insight extraction.
`insightExtractionSchedule`	`string`	`"0 2 * * *"`	Insight extraction cron schedule.
`insightExtractionMinIntervalMs`	`number`	`86400000`	Minimum interval between extractions (24h).
`memoryEnabled`	`boolean`	`true`	Enable project memory integration.
`memoryBackendType`	`string`	`"qmd"`	Memory backend type. Built-ins include `qmd` (Quantized Memory Distillation, default), `file`, and `readonly`; custom backends can also be registered.
`memoryAutoSummarizeEnabled`	`boolean`	`false`	Enable automatic memory summarization when memory exceeds threshold.
`memoryAutoSummarizeThresholdChars`	`number`	`50000`	Character threshold for auto-summarization.
`memoryAutoSummarizeSchedule`	`string`	`"0 3 * * *"`	Cron schedule for auto-summarize checks.
`memoryDreamsEnabled`	`boolean`	`false`	Enable dream processing that synthesizes daily notes and promotes durable lessons.
`memoryDreamsSchedule`	`string`	`"0 4 * * *"`	Cron schedule for dream processing.
`tokenCap`	`number`	`undefined`	Proactive token threshold for context compaction.
`runStepsInNewSessions`	`boolean`	`false`	Run each task step in a fresh agent session.
`maxParallelSteps`	`number`	`2`	Max concurrent step sessions when per-step sessions are enabled.
`missionStaleThresholdMs`	`number`	`600000`	Mission stale threshold in ms while `activating` (10 min).
`missionMaxTaskRetries`	`number`	`3`	Max automatic retries for failed mission-linked tasks.
`missionHealthCheckIntervalMs`	`number`	`300000`	Mission health-check interval in ms (5 min).
`agentPrompts`	`AgentPromptsConfig`	`undefined`	Custom role prompt templates and assignments.
`promptOverrides`	`Record<string, string \| null>`	`undefined`	Segment-level prompt overrides (set a key to `null` to clear it).
`reflectionEnabled`	`boolean`	`false`	Enable/disable agent self-reflection workflows.
`reflectionIntervalMs`	`number`	`3600000`	Periodic reflection interval in ms.
`reflectionAfterTask`	`boolean`	`true`	Trigger reflection after task completion.
`reviewHandoffPolicy`	`"disabled" \| "comment-triggered" \| "always"`	`"disabled"`	Policy for agent-to-user review handoff detection.
`showQuickChatFAB`	`boolean`	`false`	Show floating quick-chat button (chat remains available via More menu).
`experimentalFeatures`	`Record<string, boolean>`	`{}`	Project-scoped experimental feature flags.

Note: Agent metadata.skills is not a top-level project setting, but it is the primary mechanism for controlling execution-time skill selection. The engine's buildSessionSkillContext function reads this metadata from the assigned agent and uses it to resolve which skills are available in the agent session. If metadata.skills is absent or empty, the engine falls back to role-based skills (executor, reviewer, merger, triage).

Model Selection Hierarchy

Fusion uses a dual-scope model settings system with five lanes. Global settings provide baseline defaults, and project settings provide per-project overrides.

Triage/specification model

Per-task planningModelProvider + planningModelId
Project planningProvider + planningModelId
Global planningGlobalProvider + planningGlobalModelId
Project defaultProviderOverride + defaultModelIdOverride
Global defaultProvider + defaultModelId
Automatic provider/model resolution

Executor model

Per-task modelProvider + modelId
Project executionProvider + executionModelId
Global executionGlobalProvider + executionGlobalModelId
Project defaultProviderOverride + defaultModelIdOverride
Global defaultProvider + defaultModelId
Automatic provider/model resolution

Reviewer model

Per-task validatorModelProvider + validatorModelId
Project validatorProvider + validatorModelId
Global validatorGlobalProvider + validatorGlobalModelId
Project defaultProviderOverride + defaultModelIdOverride
Global defaultProvider + defaultModelId
Automatic provider/model resolution

Title summarization model

Project titleSummarizerProvider + titleSummarizerModelId
Global titleSummarizerGlobalProvider + titleSummarizerGlobalModelId
Project planningProvider + planningModelId
Project defaultProviderOverride + defaultModelIdOverride
Global defaultProvider + defaultModelId
Automatic provider/model resolution

Note: Runtime fallback precedence logic is implemented in engine and dashboard routes (FN-1711). The hierarchy above reflects the full schema contracts added in FN-1710.

Prompt Overrides

Fusion supports fine-grained customization of AI agent prompts through the promptOverrides setting. This enables surgical customization of specific prompt segments without replacing entire role prompts (which agentPrompts does).

Supported Prompt Keys

Key	Agent Role	Description
`executor-welcome`	executor	Introductory section for the executor agent
`executor-guardrails`	executor	Behavioral guardrails and constraints
`executor-spawning`	executor	Instructions for spawning child agents
`executor-completion`	executor	Completion criteria and signaling
`triage-welcome`	triage	Introductory section for the triage/specification agent
`triage-context`	triage	Context-gathering instructions
`reviewer-verdict`	reviewer	Verdict criteria and format
`merger-conflicts`	merger	Merge conflict resolution instructions
`agent-generation-system`	—	System prompt for AI-assisted agent specification generation
`workflow-step-refine`	—	System prompt for refining workflow step descriptions into detailed agent prompts

How It Works

Override Selection: When a prompt key is present with a non-empty value, that override replaces the default prompt segment.
Fallback to Defaults: Missing or empty values fall back to the built-in default content.
Cascade: agentPrompts provides full-role template customization, while promptOverrides provides segment-level customization. Both can be used together — promptOverrides applies to the segment even within a custom role template.

Clearing Overrides

To clear a specific override, set it to null:

{
  "promptOverrides": {
    "executor-welcome": null
  }
}

To clear all overrides, set promptOverrides to null:

{
  "promptOverrides": null
}

Configuration Example

{
  "settings": {
    "promptOverrides": {
      "executor-welcome": "Custom executor welcome message for this project...",
      "executor-guardrails": "## Custom Guardrails\n- Project-specific rules...",
      "triage-welcome": "Custom triage introduction..."
    }
  }
}

JSON Examples

1) Team baseline for reliable automation

{
  "settings": {
    "maxConcurrent": 3,
    "maxWorktrees": 6,
    "mergeStrategy": "direct",
    "autoResolveConflicts": true,
    "taskStuckTimeoutMs": 600000,
    "runStepsInNewSessions": true,
    "maxParallelSteps": 2
  }
}

2) Multi-model routing for plan/execute/review

{
  "settings": {
    "defaultProvider": "anthropic",
    "defaultModelId": "claude-sonnet-4-5",
    "planningProvider": "openai",
    "planningModelId": "gpt-4.1",
    "validatorProvider": "openai",
    "validatorModelId": "gpt-4o"
  }
}

3) Size-based preset auto-selection

{
  "settings": {
    "modelPresets": [
      {
        "id": "small-fast",
        "name": "Small / Fast",
        "executorProvider": "openai",
        "executorModelId": "gpt-4o-mini"
      },
      {
        "id": "large-deep",
        "name": "Large / Deep",
        "executorProvider": "anthropic",
        "executorModelId": "claude-sonnet-4-5",
        "validatorProvider": "openai",
        "validatorModelId": "gpt-4o"
      }
    ],
    "autoSelectModelPreset": true,
    "defaultPresetBySize": {
      "S": "small-fast",
      "L": "large-deep"
    }
  }
}

See also: Workflow Steps for how scripts and workflow model overrides are used.

Experimental Features

The experimentalFeatures setting provides a first-class mechanism for managing project-scoped experimental feature toggles. This allows teams to explicitly mark capabilities as experimental and toggle them on/off from a dedicated section in the Settings dashboard.

How It Works

Feature Registry: Features are stored as key-value pairs where keys are feature names and values indicate enabled/disabled state.
Default Behavior: Features not present in the map are considered disabled (fallback to false).
UI Integration: The Experimental Features section in Settings provides toggle controls for each configured feature.
Consumption: Engine code can read experimentalFeatures[key] to check if a feature is enabled.

Example JSON Shape

{
  "settings": {
    "experimentalFeatures": {
      "my-new-feature": true,
      "another-experiment": false
    }
  }
}

Dashboard UI

The Experimental Features section in Settings shows:

Feature name and enabled/disabled toggle for each configured feature
Project scope indicator (features are project-specific, not global)
Description explaining the purpose of experimental features

Background Memory Summarization & Audit

Fusion can automatically extract insights from project memory and prune transient content on a schedule. This feature is disabled by default and can be enabled via settings.

How It Works

Scheduled Extraction: When insightExtractionEnabled is true, a background automation runs on the configured insightExtractionSchedule (default: daily at 2 AM).
AI-Powered Analysis: The automation uses an AI agent to read canonical long-term memory (.fusion/memory/MEMORY.md) from the layered .fusion/memory/ workspace plus .fusion/memory-insights.md, extract new insights, and produce a pruned working memory candidate.
Insight Merging: New insights are automatically merged into .fusion/memory-insights.md under the appropriate category (Patterns, Principles, Conventions, Pitfalls, Context). Duplicates are skipped.
Memory Pruning: The AI agent also produces a pruned version of working memory containing only durable items:
- Preserved: Architecture, Conventions, Pitfalls, Context sections with durable content
- Pruned: Task-specific notes, one-time observations, outdated entries
Audit Report: After each extraction run, a .fusion/memory-audit.md file is generated with:
- Working memory status (presence, size, sections)
- Insights memory status (insight counts by category)
- Last extraction results (success/failure, insight count, duplicates skipped)
- Pruning outcome (applied/skipped, size delta, reason)
- Health status (healthy/warning/issues)
- Individual audit checks

Output Files

File	Description
`.fusion/memory/MEMORY.md`	Long-term memory (updated when pruning is applied and validated)
`.fusion/memory.md`	Deprecated legacy fallback (migration compatibility only; not canonical storage)
`.fusion/memory-insights.md`	Long-term insights distilled from working memory
`.fusion/memory-audit.md`	Human-readable audit report after each extraction

Settings Interaction

Setting	Effect
`insightExtractionEnabled`	Enables/disables the automation
`insightExtractionSchedule`	Cron expression for when extraction runs (default: `"0 2 * * *"` = daily at 2 AM)
`insightExtractionMinIntervalMs`	Minimum time between extractions (default: 24 hours)

Safety Guarantees

Pruning validation: Before pruning is applied, the candidate is validated to ensure it preserves at least 2 of 3 required sections (Architecture, Conventions, Pitfalls). Invalid candidates are safely ignored.
Graceful failures: Malformed AI output does not destroy existing memory. Prior files are preserved.
Isolated processing: Post-run callback errors are logged but do not flip successful runs to failed.
Startup sync: Automation schedule is synchronized before the cron runner starts, preventing stale config races.
Non-destructive by default: If the AI produces no prune candidate or validation fails, working memory remains unchanged.

Configuration Example

{
  "settings": {
    "insightExtractionEnabled": true,
    "insightExtractionSchedule": "0 2 * * *",
    "insightExtractionMinIntervalMs": 86400000
  }
}

Cron Expression Format

Standard cron format: minute hour day-of-month month day-of-week

Expression	Meaning
`0 2 * * *`	Daily at 2:00 AM (default)
`0 /6 * *`	Every 6 hours
`0 9 * * 1`	Weekly on Monday at 9:00 AM

Scheduling Scope

Fusion supports scoped automations and routines:

Global scope (scope: "global") — Executes across all projects. Useful for backups, insight extraction, and cross-project maintenance.
Project scope (scope: "project") — Executes within a single project only. Useful for project-specific CI, tests, and deployments.

Defaults and resolution:

When scope is omitted, Fusion treats the entry as project scope with projectId: "default".
Global-scope entries ignore projectId.
Project-scope lookups require projectId; missing values fall back to "default".

Settings that interact with scheduling:

autoBackupEnabled / autoBackupSchedule — Backup automation respects scope like any other scheduled task.
insightExtractionEnabled / insightExtractionSchedule — Insight extraction can be configured as global or project-scoped.

26 KiB Raw Blame History

Settings Reference

Settings Scopes

Settings API Endpoints

Global Settings

Project Settings

Model Selection Hierarchy

Triage/specification model

Executor model

Reviewer model

Title summarization model

Prompt Overrides

Supported Prompt Keys

How It Works

Clearing Overrides

Configuration Example

JSON Examples

1) Team baseline for reliable automation

2) Multi-model routing for plan/execute/review

3) Size-based preset auto-selection

Experimental Features

How It Works

Example JSON Shape

Dashboard UI

Background Memory Summarization & Audit

How It Works

Output Files

Settings Interaction

Safety Guarantees

Configuration Example

Cron Expression Format

Scheduling Scope

26 KiB

Raw Blame History