App Settings Plugin

A simple, generic settings management plugin for Fractal Synapse agents that provides persistent storage of both app-specific and shared settings.

Features

• Two-tier settings: App-specific settings and shared global settings
• Auto-save: Every setting change triggers immediate persistence
• Type-safe: Full TypeScript support with generics
• Storage integration: Uses storage-fs plugin for file-based persistence
• Simple API: Easy-to-use methods for getting and setting values

Installation

npm install @fractal-synapse/app-settings

Usage

Basic Setup

import { AppSettingsPlugin } from '@fractal-synapse/app-settings';

// Define your app-specific settings interface
interface MyAppSettings {
  theme: 'light' | 'dark' | 'system';
  modelOverride?: string;
  enableFeatureX: boolean;
}

// Create plugin instance
const settingsPlugin = new AppSettingsPlugin<MyAppSettings>({
  appId: 'my-app',
  defaultAppSettings: {
    theme: 'system',
    enableFeatureX: false
  },
  defaultSharedSettings: {
    apiTimeout: 30000,
    debug: false
  }
});

// Register with agent
const pluginRegistry = new PluginRegistry();
pluginRegistry.register(settingsPlugin);

const agent = new Agent({ 
  agentDefinition: new AgentDefinition(
    'My App',
    'Description',
    'System prompt',
    [],
    'openai-gpt-4o',
    ['app-settings', 'storage-fs'] // Include storage-fs for persistence
  ),
  pluginRegistry 
});

App-Specific Settings

// Get individual setting
const theme = settingsPlugin.getAppSetting('theme'); // 'system'

// Set individual setting
await settingsPlugin.setAppSetting('theme', 'dark');

// Get all app settings
const allAppSettings = settingsPlugin.getAppSettings();

// Set multiple settings
await settingsPlugin.setAppSettings({
  theme: 'light',
  enableFeatureX: true
});

// Reset to defaults
await settingsPlugin.resetAppSettings();

Shared Settings

// Get shared setting
const timeout = settingsPlugin.getSharedSetting('apiTimeout'); // 30000

// Set shared setting
await settingsPlugin.setSharedSetting('apiTimeout', 60000);

// Get all shared settings
const allSharedSettings = settingsPlugin.getSharedSettings();

// Set multiple shared settings
await settingsPlugin.setSharedSettings({
  debug: true,
  logLevel: 'verbose'
});

// Reset shared settings to defaults
await settingsPlugin.resetSharedSettings();

Examples

Agent Desktop Settings

interface DesktopSettings {
  theme: 'light' | 'dark' | 'system';
  modelOverride?: string;
  providers: { name: string; apiKey: string }[];
  windowSettings: {
    width: number;
    height: number;
    maximized: boolean;
  };
}

const desktopSettingsPlugin = new AppSettingsPlugin<DesktopSettings>({
  appId: 'agent-desktop',
  defaultAppSettings: {
    theme: 'system',
    providers: [],
    windowSettings: {
      width: 1200,
      height: 800,
      maximized: false
    }
  },
  defaultSharedSettings: {
    telemetryEnabled: true,
    autoUpdate: true
  }
});

// Usage examples
await desktopSettingsPlugin.setAppSetting('theme', 'dark');
await desktopSettingsPlugin.setAppSetting('windowSettings', {
  width: 1400,
  height: 900,
  maximized: true
});

const providers = desktopSettingsPlugin.getAppSetting('providers');
providers.push({ name: 'OpenAI', apiKey: 'sk-...' });
await desktopSettingsPlugin.setAppSetting('providers', providers);

Agent CLI Settings

interface CLISettings {
  modelOverride?: string;
  providers: { name: string; apiKey: string }[];
  outputFormat: 'text' | 'json' | 'markdown';
  verbose: boolean;
}

const cliSettingsPlugin = new AppSettingsPlugin<CLISettings>({
  appId: 'agent-cli',
  defaultAppSettings: {
    providers: [],
    outputFormat: 'text',
    verbose: false
  },
  defaultSharedSettings: {
    historyLimit: 100
  }
});

// Usage examples
await cliSettingsPlugin.setAppSetting('outputFormat', 'json');
await cliSettingsPlugin.setAppSetting('verbose', true);

// Add a provider
const providers = cliSettingsPlugin.getAppSetting('providers');
providers.push({ name: 'Anthropic', apiKey: 'sk-ant-...' });
await cliSettingsPlugin.setAppSetting('providers', providers);

Custom Application Settings

interface GameSettings {
  difficulty: 'easy' | 'normal' | 'hard';
  soundEnabled: boolean;
  musicVolume: number;
  controls: {
    up: string;
    down: string;
    left: string;
    right: string;
  };
}

const gameSettingsPlugin = new AppSettingsPlugin<GameSettings>({
  appId: 'my-game',
  defaultAppSettings: {
    difficulty: 'normal',
    soundEnabled: true,
    musicVolume: 0.7,
    controls: {
      up: 'W',
      down: 'S',
      left: 'A',
      right: 'D'
    }
  }
});

// Customize controls
await gameSettingsPlugin.setAppSetting('controls', {
  up: 'ArrowUp',
  down: 'ArrowDown',
  left: 'ArrowLeft',
  right: 'ArrowRight'
});

API Reference

Constructor

new AppSettingsPlugin<T>(config: AppSettingsConfig<T>)

AppSettingsConfig:

• appId: string - Unique identifier for the app (used in filename)
• defaultAppSettings?: T - Default values for app-specific settings
• defaultSharedSettings?: Record<string, any> - Default values for shared settings

App Settings Methods

• getAppSetting<K extends keyof T>(key: K): T[K] - Get individual app setting
• setAppSetting<K extends keyof T>(key: K, value: T[K]): Promise<void> - Set individual app setting
• getAppSettings(): T - Get all app settings
• setAppSettings(settings: Partial<T>): Promise<void> - Set multiple app settings
• resetAppSettings(): Promise<void> - Reset app settings to defaults

Shared Settings Methods

• getSharedSetting(key: string): any - Get individual shared setting
• setSharedSetting(key: string, value: any): Promise<void> - Set individual shared setting
• getSharedSettings(): Record<string, any> - Get all shared settings
• setSharedSettings(settings: Record<string, any>): Promise<void> - Set multiple shared settings
• resetSharedSettings(): Promise<void> - Reset shared settings to defaults

Utility Methods

• resetAllSettings(): Promise<void> - Reset both app and shared settings to defaults

Storage

Settings are automatically saved to {appId}-settings.json in the storage directory managed by the storage-fs plugin. The file structure is:

{
  "app": {
    // App-specific settings
  },
  "shared": {
    // Shared settings
  }
}

Requirements

• @fractal-synapse/agent-core - Core agent functionality
• @fractal-synapse/storage-fs - File system storage plugin (for persistence)

License

ISC