import type { ServiceTier, Transport } from "@earendil-works/pi-ai";
import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
import { homedir } from "os";
import { dirname, join } from "path";
import lockfile from "proper-lockfile";
import { CONFIG_DIR_NAME, getAgentDir } from "../config.js";
const RECENT_MODELS_LIMIT = 20;
export const DEFAULT_IDLE_EVICTION_MINUTES = 90;
export interface CompactionSettings {
enabled?: boolean; // default: true
reserveTokens?: number; // default: 16384
keepRecentTokens?: number; // default: 20000
agentCallable?: boolean; // default: true - expose the compact skill so the model can request compaction
}
export interface BranchSummarySettings {
reserveTokens?: number; // default: 16384 (tokens reserved for prompt + LLM response)
skipPrompt?: boolean; // default: false - when true, skips "Summarize branch?" prompt and defaults to no summary
}
export interface AutoRefineSettings {
enabled?: boolean; // default: true
turnInterval?: number; // default: 25 assistant turns
compact?: boolean; // default: true
cooldownMs?: number; // default: 20 minutes
}
export interface ProviderRetrySettings {
timeoutMs?: number; // SDK/provider request timeout in milliseconds
maxRetries?: number; // SDK/provider retry attempts
maxRetryDelayMs?: number; // default: 60000 (max server-requested delay before failing)
}
export interface RetrySettings {
enabled?: boolean; // default: true
maxRetries?: number; // default: 3
baseDelayMs?: number; // default: 2000 (exponential backoff: 2s, 4s, 8s)
provider?: ProviderRetrySettings;
}
export interface TerminalSettings {
showImages?: boolean; // default: true (show image type and dimensions)
clearOnShrink?: boolean; // default: false (clear empty rows when content shrinks)
showTerminalProgress?: boolean; // default: false (OSC 9;4 terminal progress indicators)
fullscreen?: boolean; // default: true (alternate-screen rendering with scrollable transcript)
fullscreenMouse?: boolean; // default: true
}
export interface ImageSettings {
autoResize?: boolean; // default: true (resize images to 2000x2000 max for better model compatibility)
blockImages?: boolean; // default: false - when true, prevents all images from being sent to LLM providers
}
export interface ThinkingBudgetsSettings {
minimal?: number;
low?: number;
medium?: number;
high?: number;
}
export type MermaidRenderingMode = "off" | "final" | "streaming";
export interface MarkdownSettings {
codeBlockIndent?: string; // default: " "
mermaid?: MermaidRenderingMode; // default: "streaming"
}
export interface BundledSkillsSettings {
websearch?: boolean; // default: true
}
export interface WarningSettings {
anthropicExtraUsage?: boolean; // default: true
}
export type TransportSetting = Transport;
/**
* Package source for npm/git packages.
* - String form: load all resources from the package
* - Object form: filter which resources to load
*/
export type PackageSource =
| string
| {
source: string;
extensions?: string[];
skills?: string[];
prompts?: string[];
themes?: string[];
};
/**
* Remote/local MCP server an integration connects to. Built-in integrations
* (Linear/Notion) are defined in the ai/mcp catalog; this is for user-declared
* servers. The kernel-side integration package reads creds from auth.json
* (`mcp:<name>`); login/refresh run host-side.
*/
export type McpServerConfig =
| {
type: "http";
url: string;
headers?: Record<string, string>;
/** Env var holding a static bearer token (skips OAuth). */
bearerTokenEnvVar?: string;
/** Use the generic OAuth login flow for this server. */
oauth?: boolean;
/** Force-disable even when credentials exist. */
enabled?: boolean;
enabledTools?: string[];
disabledTools?: string[];
startupTimeoutMs?: number;
callTimeoutMs?: number;
}
| {
type: "stdio";
command: string;
args?: string[];
cwd?: string;
/** Environment variables resolved from the kernel environment. */
env?: Record<string, { env: string }>;
enabled?: boolean;
enabledTools?: string[];
disabledTools?: string[];
startupTimeoutMs?: number;
callTimeoutMs?: number;
};
export interface Settings {
onboardingShown?: boolean;
onboardingCompleted?: boolean;
defaultProvider?: string;
defaultModel?: string;
recentModels?: string[]; // "provider/id" keys, most-recently-used first
defaultThinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
defaultServiceTier?: ServiceTier;
rlmMaxDepth?: number; // default for new sessions; unset falls through to RLM_MAX_DEPTH, then 2
idleEvictionMinutes?: number | "off"; // global daemon policy; default: 90
transport?: TransportSetting; // default: "auto"
steeringMode?: "all" | "one-at-a-time";
followUpMode?: "all" | "one-at-a-time";
theme?: string;
compaction?: CompactionSettings;
autoRefine?: AutoRefineSettings;
agentTraces?: AgentTracesSettings;
telemetry?: TelemetrySettings;
branchSummary?: BranchSummarySettings;
retry?: RetrySettings;
hideThinkingBlock?: boolean;
shellPath?: string; // Custom shell path (e.g., for Cygwin users on Windows)
quietStartup?: boolean;
shellCommandPrefix?: string; // Prefix prepended to every bash command (e.g., "shopt -s expand_aliases" for alias support)
npmCommand?: string[]; // Command used for npm package lookup/install operations, argv-style (e.g., ["mise", "exec", "node@20", "--", "npm"])
mcpServers?: Record<string, McpServerConfig>; // User-declared MCP servers (name → config); built-ins are in the ai/mcp catalog
packages?: PackageSource[]; // Array of npm/git package sources (string or object with filtering)
extensions?: string[]; // Array of local extension file paths or directories
skills?: string[]; // Array of local skill file paths or directories
prompts?: string[]; // Array of local prompt template paths or directories
themes?: string[]; // Array of local theme file paths or directories
enableSkillCommands?: boolean; // default: true - register skills as /skill:name commands
bundledSkills?: BundledSkillsSettings; // Configure built-in skills shipped with Prime Agent
enableBuiltinSkills?: boolean; // default: true - load built-in skills shipped with prime-agent
terminal?: TerminalSettings;
images?: ImageSettings;
enabledModels?: string[]; // Model patterns for cycling (same format as --models CLI flag)
treeFilterMode?: "default" | "no-tools" | "user-only" | "labeled-only" | "all"; // Default: "user-only"
thinkingBudgets?: ThinkingBudgetsSettings; // Custom token budgets for thinking levels
editorPaddingX?: number; // Horizontal padding for input editor (default: 0)
autocompleteMaxVisible?: number; // Max visible items in autocomplete dropdown (default: 5)
showHardwareCursor?: boolean; // Show terminal cursor while still positioning it for IME
markdown?: MarkdownSettings;
warnings?: WarningSettings;
sessionDir?: string; // Custom session storage directory (same format as --session-dir CLI flag)
}
export interface AgentTracesSettings {
enabled?: boolean;
}
export interface TelemetrySettings {
enabled?: boolean;
noticeShown?: boolean;
}
/** Deep merge settings: project/overrides take precedence, nested objects merge recursively */
function deepMergeSettings(base: Settings, overrides: Settings): Settings {
const result: Settings = { ...base };
for (const key of Object.keys(overrides) as (keyof Settings)[]) {
const overrideValue = overrides[key];
const baseValue = base[key];
if (overrideValue === undefined) {
continue;
}
if (
typeof overrideValue === "object" &&
overrideValue !== null &&
!Array.isArray(overrideValue) &&
typeof baseValue === "object" &&
baseValue !== null &&
!Array.isArray(baseValue)
) {
(result as Record<string, unknown>)[key] = { ...baseValue, ...overrideValue };
} else {
(result as Record<string, unknown>)[key] = overrideValue;
}
}
return result;
}
export type SettingsScope = "global" | "project";
export interface SettingsStorage {
withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void;
}
export interface SettingsError {
scope: SettingsScope;
error: Error;
}
export class FileSettingsStorage implements SettingsStorage {
private globalSettingsPath: string;
private projectSettingsPath: string;
constructor(cwd: string, agentDir: string) {
this.globalSettingsPath = join(agentDir, "settings.json");
this.projectSettingsPath = join(cwd, CONFIG_DIR_NAME, "settings.json");
}
private acquireLockSyncWithRetry(path: string): () => void {
const maxAttempts = 10;
const delayMs = 20;
let lastError: unknown;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
return lockfile.lockSync(path, { realpath: false });
} catch (error) {
const code =
typeof error === "object" && error !== null && "code" in error
? String((error as { code?: unknown }).code)
: undefined;
if (code !== "ELOCKED" || attempt === maxAttempts) {
throw error;
}
lastError = error;
const start = Date.now();
while (Date.now() - start < delayMs) {
// Sleep synchronously to avoid changing callers to async.
}
}
}
throw (lastError as Error) ?? new Error("Failed to acquire settings lock");
}
withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void {
const path = scope === "global" ? this.globalSettingsPath : this.projectSettingsPath;
const dir = dirname(path);
let release: (() => void) | undefined;
try {
const fileExists = existsSync(path);
if (fileExists) {
release = this.acquireLockSyncWithRetry(path);
}
const current = fileExists ? readFileSync(path, "utf-8") : undefined;
const next = fn(current);
if (next !== undefined) {
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
if (!release) {
release = this.acquireLockSyncWithRetry(path);
}
const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
try {
writeFileSync(temporaryPath, next, { encoding: "utf-8", mode: 0o600 });
renameSync(temporaryPath, path);
} finally {
if (existsSync(temporaryPath)) unlinkSync(temporaryPath);
}
}
} finally {
if (release) {
release();
}
}
}
}
export class InMemorySettingsStorage implements SettingsStorage {
private global: string | undefined;
private project: string | undefined;
withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void {
const current = scope === "global" ? this.global : this.project;
const next = fn(current);
if (next !== undefined) {
if (scope === "global") {
this.global = next;
} else {
this.project = next;
}
}
}
}
export class SettingsManager {
private storage: SettingsStorage;
private globalSettings: Settings;
private projectSettings: Settings;
private settings: Settings;
private runtimeOverrides: Settings = {};
private modifiedFields = new Set<keyof Settings>(); // Track global fields modified during session
private modifiedNestedFields = new Map<keyof Settings, Set<string>>(); // Track global nested field modifications
private modifiedProjectFields = new Set<keyof Settings>(); // Track project fields modified during session
private modifiedProjectNestedFields = new Map<keyof Settings, Set<string>>(); // Track project nested field modifications
private globalSettingsLoadError: Error | null = null; // Track if global settings file had parse errors
private projectSettingsLoadError: Error | null = null; // Track if project settings file had parse errors
private writeQueue: Promise<void> = Promise.resolve();
private errors: SettingsError[];
private constructor(
storage: SettingsStorage,
initialGlobal: Settings,
initialProject: Settings,
globalLoadError: Error | null = null,
projectLoadError: Error | null = null,
initialErrors: SettingsError[] = [],
) {
this.storage = storage;
this.globalSettings = initialGlobal;
this.projectSettings = initialProject;
this.globalSettingsLoadError = globalLoadError;
this.projectSettingsLoadError = projectLoadError;
this.errors = [...initialErrors];
this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
}
/** Create a SettingsManager that loads from files */
static create(cwd: string, agentDir: string = getAgentDir()): SettingsManager {
const storage = new FileSettingsStorage(cwd, agentDir);
return SettingsManager.fromStorage(storage);
}
/** Create a SettingsManager from an arbitrary storage backend */
static fromStorage(storage: SettingsStorage): SettingsManager {
const globalLoad = SettingsManager.tryLoadFromStorage(storage, "global");
const projectLoad = SettingsManager.tryLoadFromStorage(storage, "project");
const initialErrors: SettingsError[] = [];
if (globalLoad.error) {
initialErrors.push({ scope: "global", error: globalLoad.error });
}
if (projectLoad.error) {
initialErrors.push({ scope: "project", error: projectLoad.error });
}
return new SettingsManager(
storage,
globalLoad.settings,
projectLoad.settings,
globalLoad.error,
projectLoad.error,
initialErrors,
);
}
/** Create an in-memory SettingsManager (no file I/O) */
static inMemory(settings: Partial<Settings> = {}): SettingsManager {
const storage = new InMemorySettingsStorage();
const initialSettings = SettingsManager.migrateSettings(structuredClone(settings) as Record<string, unknown>);
storage.withLock("global", () => JSON.stringify(initialSettings, null, 2));
return SettingsManager.fromStorage(storage);
}
private static loadFromStorage(storage: SettingsStorage, scope: SettingsScope): Settings {
let content: string | undefined;
storage.withLock(scope, (current) => {
content = current;
return undefined;
});
if (!content) {
return {};
}
const settings = JSON.parse(content);
return SettingsManager.migrateSettings(settings);
}
private static tryLoadFromStorage(
storage: SettingsStorage,
scope: SettingsScope,
): { settings: Settings; error: Error | null } {
try {
return { settings: SettingsManager.loadFromStorage(storage, scope), error: null };
} catch (error) {
return { settings: {}, error: error as Error };
}
}
/** Migrate old settings format to new format */
private static migrateSettings(settings: Record<string, unknown>): Settings {
if ("queueMode" in settings && !("steeringMode" in settings)) {
settings.steeringMode = settings.queueMode;
delete settings.queueMode;
}
if (!("transport" in settings) && typeof settings.websockets === "boolean") {
settings.transport = settings.websockets ? "websocket" : "sse";
delete settings.websockets;
}
if (
"skills" in settings &&
typeof settings.skills === "object" &&
settings.skills !== null &&
!Array.isArray(settings.skills)
) {
const skillsSettings = settings.skills as {
enableSkillCommands?: boolean;
customDirectories?: unknown;
};
if (skillsSettings.enableSkillCommands !== undefined && settings.enableSkillCommands === undefined) {
settings.enableSkillCommands = skillsSettings.enableSkillCommands;
}
if (Array.isArray(skillsSettings.customDirectories) && skillsSettings.customDirectories.length > 0) {
settings.skills = skillsSettings.customDirectories;
} else {
delete settings.skills;
}
}
if (
"retry" in settings &&
typeof settings.retry === "object" &&
settings.retry !== null &&
!Array.isArray(settings.retry)
) {
const retrySettings = settings.retry as Record<string, unknown>;
const providerSettings =
typeof retrySettings.provider === "object" && retrySettings.provider !== null
? (retrySettings.provider as Record<string, unknown>)
: undefined;
if (
typeof retrySettings.maxDelayMs === "number" &&
(providerSettings?.maxRetryDelayMs === undefined || providerSettings?.maxRetryDelayMs === null)
) {
retrySettings.provider = {
...(providerSettings ?? {}),
maxRetryDelayMs: retrySettings.maxDelayMs,
};
}
delete retrySettings.maxDelayMs;
}
if (typeof settings.telemetry === "boolean") {
settings.telemetry = { enabled: settings.telemetry };
} else if (
settings.telemetry !== undefined &&
(typeof settings.telemetry !== "object" || settings.telemetry === null || Array.isArray(settings.telemetry))
) {
delete settings.telemetry;
}
if (
settings.markdown !== undefined &&
(typeof settings.markdown !== "object" || settings.markdown === null || Array.isArray(settings.markdown))
) {
delete settings.markdown;
}
return settings as Settings;
}
getGlobalSettings(): Settings {
return structuredClone(this.globalSettings);
}
getProjectSettings(): Settings {
return structuredClone(this.projectSettings);
}
async reload(): Promise<void> {
await this.writeQueue;
const globalLoad = SettingsManager.tryLoadFromStorage(this.storage, "global");
if (!globalLoad.error) {
this.globalSettings = globalLoad.settings;
this.globalSettingsLoadError = null;
} else {
this.globalSettingsLoadError = globalLoad.error;
this.recordError("global", globalLoad.error);
}
this.modifiedFields.clear();
this.modifiedNestedFields.clear();
this.modifiedProjectFields.clear();
this.modifiedProjectNestedFields.clear();
const projectLoad = SettingsManager.tryLoadFromStorage(this.storage, "project");
if (!projectLoad.error) {
this.projectSettings = projectLoad.settings;
this.projectSettingsLoadError = null;
} else {
this.projectSettingsLoadError = projectLoad.error;
this.recordError("project", projectLoad.error);
}
this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
}
/** Apply additional overrides on top of current settings */
applyOverrides(overrides: Partial<Settings>): void {
this.runtimeOverrides = deepMergeSettings(this.runtimeOverrides, overrides);
this.settings = deepMergeSettings(this.settings, overrides);
}
/** Mark a global field as modified during this session */
private markModified(field: keyof Settings, nestedKey?: string): void {
this.modifiedFields.add(field);
if (nestedKey) {
if (!this.modifiedNestedFields.has(field)) {
this.modifiedNestedFields.set(field, new Set());
}
this.modifiedNestedFields.get(field)!.add(nestedKey);
}
}
/** Mark a project field as modified during this session */
private markProjectModified(field: keyof Settings, nestedKey?: string): void {
this.modifiedProjectFields.add(field);
if (nestedKey) {
if (!this.modifiedProjectNestedFields.has(field)) {
this.modifiedProjectNestedFields.set(field, new Set());
}
this.modifiedProjectNestedFields.get(field)!.add(nestedKey);
}
}
private recordError(scope: SettingsScope, error: unknown): void {
const normalizedError = error instanceof Error ? error : new Error(String(error));
this.errors.push({ scope, error: normalizedError });
}
private clearModifiedScope(scope: SettingsScope): void {
if (scope === "global") {
this.modifiedFields.clear();
this.modifiedNestedFields.clear();
return;
}
this.modifiedProjectFields.clear();
this.modifiedProjectNestedFields.clear();
}
private enqueueWrite(scope: SettingsScope, task: () => void): void {
this.writeQueue = this.writeQueue
.then(() => {
task();
this.clearModifiedScope(scope);
})
.catch((error) => {
this.recordError(scope, error);
});
}
private cloneModifiedNestedFields(source: Map<keyof Settings, Set<string>>): Map<keyof Settings, Set<string>> {
const snapshot = new Map<keyof Settings, Set<string>>();
for (const [key, value] of source.entries()) {
snapshot.set(key, new Set(value));
}
return snapshot;
}
private persistScopedSettings(
scope: SettingsScope,
snapshotSettings: Settings,
modifiedFields: Set<keyof Settings>,
modifiedNestedFields: Map<keyof Settings, Set<string>>,
): void {
this.storage.withLock(scope, (current) => {
const currentFileSettings = current
? SettingsManager.migrateSettings(JSON.parse(current) as Record<string, unknown>)
: {};
const mergedSettings: Settings = { ...currentFileSettings };
for (const field of modifiedFields) {
const value = snapshotSettings[field];
if (modifiedNestedFields.has(field) && typeof value === "object" && value !== null) {
const nestedModified = modifiedNestedFields.get(field)!;
const baseNested = (currentFileSettings[field] as Record<string, unknown>) ?? {};
const inMemoryNested = value as Record<string, unknown>;
const mergedNested = { ...baseNested };
for (const nestedKey of nestedModified) {
mergedNested[nestedKey] = inMemoryNested[nestedKey];
}
(mergedSettings as Record<string, unknown>)[field] = mergedNested;
} else {
(mergedSettings as Record<string, unknown>)[field] = value;
}
}
return JSON.stringify(mergedSettings, null, 2);
});
}
private save(): void {
this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
if (this.globalSettingsLoadError) {
this.recordError(
"global",
new Error(
`Global settings not saved: settings file failed to parse: ${this.globalSettingsLoadError.message}`,
),
);
return;
}
const snapshotGlobalSettings = structuredClone(this.globalSettings);
const modifiedFields = new Set(this.modifiedFields);
const modifiedNestedFields = this.cloneModifiedNestedFields(this.modifiedNestedFields);
this.enqueueWrite("global", () => {
this.persistScopedSettings("global", snapshotGlobalSettings, modifiedFields, modifiedNestedFields);
});
}
private saveProjectSettings(settings: Settings): void {
this.projectSettings = structuredClone(settings);
this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
if (this.projectSettingsLoadError) {
this.recordError(
"project",
new Error(
`Project settings not saved: settings file failed to parse: ${this.projectSettingsLoadError.message}`,
),
);
return;
}
const snapshotProjectSettings = structuredClone(this.projectSettings);
const modifiedFields = new Set(this.modifiedProjectFields);
const modifiedNestedFields = this.cloneModifiedNestedFields(this.modifiedProjectNestedFields);
this.enqueueWrite("project", () => {
this.persistScopedSettings("project", snapshotProjectSettings, modifiedFields, modifiedNestedFields);
});
}
async flush(): Promise<void> {
await this.writeQueue;
}
drainErrors(scope?: SettingsScope): SettingsError[] {
if (!scope) {
const drained = [...this.errors];
this.errors = [];
return drained;
}
const drained = this.errors.filter((entry) => entry.scope === scope);
this.errors = this.errors.filter((entry) => entry.scope !== scope);
return drained;
}
getOnboardingShown(): boolean {
return this.settings.onboardingShown ?? this.settings.onboardingCompleted ?? false;
}
setOnboardingShown(shown: boolean): void {
this.globalSettings.onboardingShown = shown;
this.markModified("onboardingShown");
this.save();
}
getSessionDir(): string | undefined {
const sessionDir = this.settings.sessionDir;
if (!sessionDir) {
return sessionDir;
}
if (sessionDir === "~") {
return homedir();
}
if (sessionDir.startsWith("~/")) {
return join(homedir(), sessionDir.slice(2));
}
return sessionDir;
}
getDefaultProvider(): string | undefined {
return this.settings.defaultProvider;
}
getDefaultModel(): string | undefined {
return this.settings.defaultModel;
}
setDefaultProvider(provider: string): void {
this.globalSettings.defaultProvider = provider;
this.markModified("defaultProvider");
this.save();
}
setDefaultModel(modelId: string): void {
this.globalSettings.defaultModel = modelId;
this.markModified("defaultModel");
this.save();
}
setDefaultModelAndProvider(provider: string, modelId: string): void {
this.globalSettings.defaultProvider = provider;
this.globalSettings.defaultModel = modelId;
this.markModified("defaultProvider");
this.markModified("defaultModel");
this.recordModelUseInternal(provider, modelId);
this.markModified("recentModels");
this.save();
}
getRecentModels(): string[] {
return this.settings.recentModels ?? [];
}
private recordModelUseInternal(provider: string, modelId: string): void {
const key = `${provider}/${modelId}`;
const next = [key, ...this.getRecentModels().filter((k) => k !== key)];
this.globalSettings.recentModels = next.slice(0, RECENT_MODELS_LIMIT);
}
getSteeringMode(): "all" | "one-at-a-time" {
return this.settings.steeringMode || "one-at-a-time";
}
setSteeringMode(mode: "all" | "one-at-a-time"): void {
this.globalSettings.steeringMode = mode;
this.markModified("steeringMode");
this.save();
}
getFollowUpMode(): "all" | "one-at-a-time" {
return this.settings.followUpMode || "one-at-a-time";
}
setFollowUpMode(mode: "all" | "one-at-a-time"): void {
this.globalSettings.followUpMode = mode;
this.markModified("followUpMode");
this.save();
}
getTheme(): string | undefined {
return this.settings.theme;
}
setTheme(theme: string): void {
this.globalSettings.theme = theme;
this.markModified("theme");
this.save();
}
getDefaultThinkingLevel(): "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined {
return this.settings.defaultThinkingLevel;
}
setDefaultThinkingLevel(level: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"): void {
this.globalSettings.defaultThinkingLevel = level;
this.markModified("defaultThinkingLevel");
this.save();
}
getDefaultServiceTier(): ServiceTier {
return this.settings.defaultServiceTier ?? "default";
}
setDefaultServiceTier(serviceTier: ServiceTier): void {
this.globalSettings.defaultServiceTier = serviceTier;
this.markModified("defaultServiceTier");
this.save();
}
getRlmMaxDepth(): number | undefined {
return this.globalSettings.rlmMaxDepth;
}
setRlmMaxDepth(maxDepth: number): void {
this.globalSettings.rlmMaxDepth = maxDepth;
this.markModified("rlmMaxDepth");
this.save();
}
getIdleEvictionMinutes(): number | "off" {
const value: unknown = this.globalSettings.idleEvictionMinutes;
if (value === "off" || value === "none") return "off";
return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : DEFAULT_IDLE_EVICTION_MINUTES;
}
setIdleEvictionMinutes(value: number | "off"): void {
if (value !== "off" && (!Number.isFinite(value) || value <= 0)) {
throw new Error("Idle eviction minutes must be a positive number or off");
}
this.globalSettings.idleEvictionMinutes = value;
this.markModified("idleEvictionMinutes");
this.save();
}
getTransport(): TransportSetting {
return this.settings.transport ?? "auto";
}
setTransport(transport: TransportSetting): void {
this.globalSettings.transport = transport;
this.markModified("transport");
this.save();
}
getCompactionEnabled(): boolean {
return this.settings.compaction?.enabled ?? true;
}
setCompactionEnabled(enabled: boolean): void {
if (!this.globalSettings.compaction) {
this.globalSettings.compaction = {};
}
this.globalSettings.compaction.enabled = enabled;
this.markModified("compaction", "enabled");
this.save();
}
getAgentTracesEnabled(): boolean {
return this.settings.agentTraces?.enabled ?? false;
}
setAgentTracesEnabled(enabled: boolean): void {
if (!this.globalSettings.agentTraces) {
this.globalSettings.agentTraces = {};
}
this.globalSettings.agentTraces.enabled = enabled;
this.markModified("agentTraces", "enabled");
this.save();
}
getTelemetryEnabled(): boolean {
const globalEnabled = this.globalSettings.telemetry?.enabled ?? true;
const projectEnabled = this.projectSettings.telemetry?.enabled ?? true;
const runtimeEnabled = this.runtimeOverrides.telemetry?.enabled ?? true;
return globalEnabled && projectEnabled && runtimeEnabled;
}
private getOrCreateGlobalTelemetrySettings(): TelemetrySettings {
const telemetry = this.globalSettings.telemetry;
if (typeof telemetry !== "object" || telemetry === null || Array.isArray(telemetry)) {
this.globalSettings.telemetry = {};
}
return this.globalSettings.telemetry!;
}
setTelemetryEnabled(enabled: boolean): void {
this.getOrCreateGlobalTelemetrySettings().enabled = enabled;
this.markModified("telemetry", "enabled");
this.save();
}
getTelemetryNoticeShown(): boolean {
return this.runtimeOverrides.telemetry?.noticeShown ?? this.globalSettings.telemetry?.noticeShown ?? false;
}
setTelemetryNoticeShown(shown: boolean): void {
this.getOrCreateGlobalTelemetrySettings().noticeShown = shown;
this.markModified("telemetry", "noticeShown");
this.save();
}
getCompactionReserveTokens(): number {
return this.settings.compaction?.reserveTokens ?? 16384;
}
getCompactionKeepRecentTokens(): number {
return this.settings.compaction?.keepRecentTokens ?? 20000;
}
getCompactionAgentCallable(): boolean {
return this.settings.compaction?.agentCallable ?? true;
}
getCompactionSettings(): { enabled: boolean; reserveTokens: number; keepRecentTokens: number } {
return {
enabled: this.getCompactionEnabled(),
reserveTokens: this.getCompactionReserveTokens(),
keepRecentTokens: this.getCompactionKeepRecentTokens(),
};
}
getAutoRefineSettings(): { enabled: boolean; turnInterval: number; compact: boolean; cooldownMs: number } {
const turnInterval = this.settings.autoRefine?.turnInterval;
const cooldownMs = this.settings.autoRefine?.cooldownMs;
return {
enabled: this.settings.autoRefine?.enabled ?? true,
turnInterval: Math.max(
1,
typeof turnInterval === "number" && Number.isFinite(turnInterval) ? turnInterval : 25,
),
compact: this.settings.autoRefine?.compact ?? true,
cooldownMs: Math.max(
0,
typeof cooldownMs === "number" && Number.isFinite(cooldownMs) ? cooldownMs : 20 * 60_000,
),
};
}
getBranchSummarySettings(): { reserveTokens: number; skipPrompt: boolean } {
return {
reserveTokens: this.settings.branchSummary?.reserveTokens ?? 16384,
skipPrompt: this.settings.branchSummary?.skipPrompt ?? false,
};
}
getBranchSummarySkipPrompt(): boolean {
return this.settings.branchSummary?.skipPrompt ?? false;
}
getRetryEnabled(): boolean {
return this.settings.retry?.enabled ?? true;
}
setRetryEnabled(enabled: boolean): void {
if (!this.globalSettings.retry) {
this.globalSettings.retry = {};
}
this.globalSettings.retry.enabled = enabled;
this.markModified("retry", "enabled");
this.save();
}
getRetrySettings(): { enabled: boolean; maxRetries: number; baseDelayMs: number } {
return {
enabled: this.getRetryEnabled(),
maxRetries: this.settings.retry?.maxRetries ?? 3,
baseDelayMs: this.settings.retry?.baseDelayMs ?? 2000,
};
}
getProviderRetrySettings(): { timeoutMs?: number; maxRetries?: number; maxRetryDelayMs: number } {
return {
timeoutMs: this.settings.retry?.provider?.timeoutMs,
maxRetries: this.settings.retry?.provider?.maxRetries,
maxRetryDelayMs: this.settings.retry?.provider?.maxRetryDelayMs ?? 60000,
};
}
getHideThinkingBlock(): boolean {
return this.settings.hideThinkingBlock ?? false;
}
setHideThinkingBlock(hide: boolean): void {
this.globalSettings.hideThinkingBlock = hide;
this.markModified("hideThinkingBlock");
this.save();
}
getShellPath(): string | undefined {
return this.settings.shellPath;
}
setShellPath(path: string | undefined): void {
this.globalSettings.shellPath = path;
this.markModified("shellPath");
this.save();
}
getQuietStartup(): boolean {
return this.settings.quietStartup ?? false;
}
setQuietStartup(quiet: boolean): void {
this.globalSettings.quietStartup = quiet;
this.markModified("quietStartup");
this.save();
}
getShellCommandPrefix(): string | undefined {
return this.settings.shellCommandPrefix;
}
setShellCommandPrefix(prefix: string | undefined): void {
this.globalSettings.shellCommandPrefix = prefix;
this.markModified("shellCommandPrefix");
this.save();
}
getNpmCommand(): string[] | undefined {
return this.settings.npmCommand ? [...this.settings.npmCommand] : undefined;
}
setNpmCommand(command: string[] | undefined): void {
this.globalSettings.npmCommand = command ? [...command] : undefined;
this.markModified("npmCommand");
this.save();
}
getPackages(): PackageSource[] {
return [...(this.settings.packages ?? [])];
}
setPackages(packages: PackageSource[]): void {
this.globalSettings.packages = packages;
this.markModified("packages");
this.save();
}
setProjectPackages(packages: PackageSource[]): void {
const projectSettings = structuredClone(this.projectSettings);
projectSettings.packages = packages;
this.markProjectModified("packages");
this.saveProjectSettings(projectSettings);
}
getExtensionPaths(): string[] {
return [...(this.settings.extensions ?? [])];
}
setExtensionPaths(paths: string[]): void {
this.globalSettings.extensions = paths;
this.markModified("extensions");
this.save();
}
setProjectExtensionPaths(paths: string[]): void {
const projectSettings = structuredClone(this.projectSettings);
projectSettings.extensions = paths;
this.markProjectModified("extensions");
this.saveProjectSettings(projectSettings);
}
getSkillPaths(): string[] {
return [...(this.settings.skills ?? [])];
}
setSkillPaths(paths: string[]): void {
this.globalSettings.skills = paths;
this.markModified("skills");
this.save();
}
setProjectSkillPaths(paths: string[]): void {
const projectSettings = structuredClone(this.projectSettings);
projectSettings.skills = paths;
this.markProjectModified("skills");
this.saveProjectSettings(projectSettings);
}
getPromptTemplatePaths(): string[] {
return [...(this.settings.prompts ?? [])];
}
setPromptTemplatePaths(paths: string[]): void {
this.globalSettings.prompts = paths;
this.markModified("prompts");
this.save();
}
setProjectPromptTemplatePaths(paths: string[]): void {
const projectSettings = structuredClone(this.projectSettings);
projectSettings.prompts = paths;
this.markProjectModified("prompts");
this.saveProjectSettings(projectSettings);
}
getThemePaths(): string[] {
return [...(this.settings.themes ?? [])];
}
setThemePaths(paths: string[]): void {
this.globalSettings.themes = paths;
this.markModified("themes");
this.save();
}
setProjectThemePaths(paths: string[]): void {
const projectSettings = structuredClone(this.projectSettings);
projectSettings.themes = paths;
this.markProjectModified("themes");
this.saveProjectSettings(projectSettings);
}
getEnableSkillCommands(): boolean {
return this.settings.enableSkillCommands ?? true;
}
setEnableSkillCommands(enabled: boolean): void {
this.globalSettings.enableSkillCommands = enabled;
this.markModified("enableSkillCommands");
this.save();
}
getBundledSkills(): { websearch: boolean } {
return {
websearch: this.settings.bundledSkills?.websearch ?? true,
};
}
getBundledWebsearchEnabled(): boolean {
return this.getBundledSkills().websearch;
}
getEnableBuiltinSkills(): boolean {
return this.settings.enableBuiltinSkills ?? true;
}
setEnableBuiltinSkills(enabled: boolean): void {
this.globalSettings.enableBuiltinSkills = enabled;
this.markModified("enableBuiltinSkills");
this.save();
}
getThinkingBudgets(): ThinkingBudgetsSettings | undefined {
return this.settings.thinkingBudgets;
}
getShowImages(): boolean {
return this.settings.terminal?.showImages ?? true;
}
setShowImages(show: boolean): void {
if (!this.globalSettings.terminal) {
this.globalSettings.terminal = {};
}
this.globalSettings.terminal.showImages = show;
this.markModified("terminal", "showImages");
this.save();
}
getClearOnShrink(): boolean {
if (this.settings.terminal?.clearOnShrink !== undefined) {
return this.settings.terminal.clearOnShrink;
}
return process.env.PI_CLEAR_ON_SHRINK === "1";
}
setClearOnShrink(enabled: boolean): void {
if (!this.globalSettings.terminal) {
this.globalSettings.terminal = {};
}
this.globalSettings.terminal.clearOnShrink = enabled;
this.markModified("terminal", "clearOnShrink");
this.save();
}
getFullscreen(): boolean {
if (process.env.PI_FULLSCREEN !== undefined) {
return process.env.PI_FULLSCREEN === "1";
}
return this.settings.terminal?.fullscreen ?? true;
}
setFullscreen(enabled: boolean): void {
if (!this.globalSettings.terminal) {
this.globalSettings.terminal = {};
}
this.globalSettings.terminal.fullscreen = enabled;
this.markModified("terminal", "fullscreen");
this.save();
}
getFullscreenMouse(): boolean {
return this.settings.terminal?.fullscreenMouse ?? true;
}
setFullscreenMouse(enabled: boolean): void {
if (!this.globalSettings.terminal) {
this.globalSettings.terminal = {};
}
this.globalSettings.terminal.fullscreenMouse = enabled;
this.markModified("terminal", "fullscreenMouse");
this.save();
}
getShowTerminalProgress(): boolean {
return this.settings.terminal?.showTerminalProgress ?? false;
}
setShowTerminalProgress(enabled: boolean): void {
if (!this.globalSettings.terminal) {
this.globalSettings.terminal = {};
}
this.globalSettings.terminal.showTerminalProgress = enabled;
this.markModified("terminal", "showTerminalProgress");
this.save();
}
getImageAutoResize(): boolean {
return this.settings.images?.autoResize ?? true;
}
setImageAutoResize(enabled: boolean): void {
if (!this.globalSettings.images) {
this.globalSettings.images = {};
}
this.globalSettings.images.autoResize = enabled;
this.markModified("images", "autoResize");
this.save();
}
getBlockImages(): boolean {
return this.settings.images?.blockImages ?? false;
}
setBlockImages(blocked: boolean): void {
if (!this.globalSettings.images) {
this.globalSettings.images = {};
}
this.globalSettings.images.blockImages = blocked;
this.markModified("images", "blockImages");
this.save();
}
getEnabledModels(): string[] | undefined {
return this.settings.enabledModels;
}
/** MCP execution is intentionally restricted to user/global settings. */
getGlobalMcpServers(): Record<string, McpServerConfig> | undefined {
return structuredClone(this.globalSettings.mcpServers);
}
setGlobalMcpServer(name: string, config: McpServerConfig, force = false): void {
if (this.globalSettings.mcpServers?.[name] && !force) {
throw new Error(`MCP server "${name}" already exists. Use --force to replace it.`);
}
this.globalSettings.mcpServers = { ...(this.globalSettings.mcpServers ?? {}), [name]: structuredClone(config) };
this.markModified("mcpServers", name);
this.save();
}
removeGlobalMcpServer(name: string): boolean {
if (!this.globalSettings.mcpServers?.[name]) return false;
const servers = { ...this.globalSettings.mcpServers };
delete servers[name];
this.globalSettings.mcpServers = servers;
this.markModified("mcpServers", name);
this.save();
return true;
}
setEnabledModels(patterns: string[] | undefined): void {
this.globalSettings.enabledModels = patterns;
this.markModified("enabledModels");
this.save();
}
getTreeFilterMode(): "default" | "no-tools" | "user-only" | "labeled-only" | "all" {
const mode = this.settings.treeFilterMode;
const valid = ["default", "no-tools", "user-only", "labeled-only", "all"];
return mode && valid.includes(mode) ? mode : "user-only";
}
setTreeFilterMode(mode: "default" | "no-tools" | "user-only" | "labeled-only" | "all"): void {
this.globalSettings.treeFilterMode = mode;
this.markModified("treeFilterMode");
this.save();
}
getShowHardwareCursor(): boolean {
return this.settings.showHardwareCursor ?? process.env.PI_HARDWARE_CURSOR === "1";
}
setShowHardwareCursor(enabled: boolean): void {
this.globalSettings.showHardwareCursor = enabled;
this.markModified("showHardwareCursor");
this.save();
}
getEditorPaddingX(): number {
return this.settings.editorPaddingX ?? 0;
}
setEditorPaddingX(padding: number): void {
this.globalSettings.editorPaddingX = Math.max(0, Math.min(3, Math.floor(padding)));
this.markModified("editorPaddingX");
this.save();
}
getAutocompleteMaxVisible(): number {
return this.settings.autocompleteMaxVisible ?? 5;
}
setAutocompleteMaxVisible(maxVisible: number): void {
this.globalSettings.autocompleteMaxVisible = Math.max(3, Math.min(20, Math.floor(maxVisible)));
this.markModified("autocompleteMaxVisible");
this.save();
}
getCodeBlockIndent(): string {
return this.settings.markdown?.codeBlockIndent ?? " ";
}
getMermaidRenderingMode(): MermaidRenderingMode {
const mode = this.settings.markdown?.mermaid;
return mode === "off" || mode === "final" ? mode : "streaming";
}
setMermaidRenderingMode(mode: MermaidRenderingMode): void {
this.globalSettings.markdown ??= {};
this.globalSettings.markdown.mermaid = mode;
this.markModified("markdown", "mermaid");
this.save();
}
getWarnings(): WarningSettings {
return { ...(this.settings.warnings ?? {}) };
}
setWarnings(warnings: WarningSettings): void {
this.globalSettings.warnings = { ...warnings };
this.markModified("warnings");
this.save();
}
}