diff --git a/README.md b/README.md index ada8350..01a31d4 100644 --- a/README.md +++ b/README.md @@ -363,6 +363,15 @@ backends: `pi_embedded` is intended for canary migration cohorts. In spike mode (`no_tools_mode: true`), Flynn keeps tool-oriented turns on native and only routes plain-text turns to Pi. +Runtime backend mode can be controlled live (persisted in `~/.local/share/flynn/preferences.json`): + +- `/backend status` shows runtime mode and effective backend selection +- `/backend activate pi` forces `pi_embedded` globally +- `/backend deactivate pi` forces native for Pi-routed turns +- `/backend use config` resets to `backends.default` + +This manual runtime mode control is the intended Pi activation/deactivation switch. + To evaluate canary performance from audit logs, run: ```bash @@ -602,6 +611,7 @@ Notes: | `/approve [id]` | Approve latest (or specific) pending gate | | `/deny [id] [reason]` | Deny latest (or specific) pending gate | | `/skill ` | In-chat skill discovery/install (`list`, `search `, `install `) | +| `/backend ` | Show or control global runtime backend mode | ## Web UI Dashboard @@ -637,7 +647,7 @@ pnpm tui:fs | `/model` | Show all model tiers and which is active | | `/model ` | Switch active tier (`local`, `default`, `fast`, `complex`, or aliases `ollama`, `sonnet`, `haiku`, `opus`) | | `/model ` | Hot-swap a tier's provider and model at runtime | -| `/backend [provider]` | Show or switch local backend (`ollama`, `llamacpp`) | +| `/backend [provider]` | TUI-local command: show or switch local model backend (`ollama`, `llamacpp`) | | `/login [provider]` | Authenticate with GitHub (OAuth device flow) | | `/reset` | Clear history | | `/status` | Show session info | diff --git a/docs/api/PROTOCOL.md b/docs/api/PROTOCOL.md index b25f2cb..04828bd 100644 --- a/docs/api/PROTOCOL.md +++ b/docs/api/PROTOCOL.md @@ -37,6 +37,7 @@ The gateway serialises agent work **per session**, not per WebSocket connection: - Lane policy is configurable (`collect`, `followup`, `steer`, `steer_backlog`, `interrupt`) with per-channel and per-session overrides. - Session-local overrides can be managed at runtime via `agent.send` commands: `/queue`, `/queue set ...`, `/queue reset`. - Backend selection for a turn is server-side (`native` by default, optional external backends per config: `claude_code`, `opencode`, `codex`, `gemini`, `pi_embedded`) and does not change JSON-RPC method signatures. +- Runtime backend mode overrides are available via `agent.send` command fast-path: `/backend status`, `/backend activate pi`, `/backend deactivate pi`, `/backend use config`. - Backend routing and fallback outcomes are emitted to audit logs (`backend.route`, `backend.success`, `backend.fallback`) for rollout evaluation; this telemetry is outside JSON-RPC response payloads. This is implemented via a per-lane queue (`LaneQueue`) in the gateway server, and used by `agent.send` and `agent.cancel`. diff --git a/docs/architecture/AGENT_DIAGRAM.md b/docs/architecture/AGENT_DIAGRAM.md index f5e4a17..3ea9321 100644 --- a/docs/architecture/AGENT_DIAGRAM.md +++ b/docs/architecture/AGENT_DIAGRAM.md @@ -28,6 +28,7 @@ flowchart LR CA[ChannelAdapters] GW[Gateway\nHTTP + WS JSON-RPC + Web UI] RT[Routing\ncreateMessageRouter()] + PF[Preferences\n~/.local/share/flynn/preferences.json\nmodelTier + backendMode] SM[SessionManager\nSQLite] OR[AgentOrchestrator] NA[NativeAgent\n(tool loop)] @@ -55,6 +56,7 @@ flowchart LR CG --> RT CE --> RT + PF --> RT CH --> CA GW --> RT @@ -96,6 +98,9 @@ ChannelAdapter -> ChannelRegistry | v | createMessageRouter() | | + | +----> Runtime backend mode overrides + | (/backend status|activate pi|deactivate pi|use config) + | | | v | SessionManager | | @@ -134,6 +139,7 @@ Outbound Reply Key files: - Routing + per-session agent creation: `src/daemon/routing.ts` +- Runtime preference persistence (`modelTier`, `backendMode`): `src/preferences.ts` - Orchestration: `src/backends/native/orchestrator.ts` - Tool loop: `src/backends/native/agent.ts` - External backend adapters: `src/backends/external.ts`, `src/backends/piEmbedded.ts` diff --git a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md index 514223e..c685ae1 100644 --- a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md +++ b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md @@ -11,6 +11,7 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`. - Agent work is queued per `sessionId` (FIFO), not per connection. - Sessions persist in SQLite via `SessionManager` even if clients disconnect. - Once dequeued, message routing may execute the native orchestrator path or an optional external backend path (`claude_code`, `opencode`, `codex`, `gemini`, `pi_embedded`) depending on agent/backend config. +- Runtime backend mode can be overridden manually via `/backend` command fast-path (`status`, `activate pi`, `deactivate pi`, `use config`) and is persisted in preferences. - Backend routing outcomes are auditable via `backend.route` / `backend.success` / `backend.fallback`, which enables offline canary evaluation without changing gateway protocol methods. ## Component Map @@ -19,6 +20,7 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`. flowchart LR subgraph CFG[Config + Runtime Policy] QP[server.queue policy\nmode/cap/overflow/overrides] + BM[backend runtime mode\nconfig_default|force_native|force_pi_embedded] end subgraph GW[Gateway Process] @@ -37,6 +39,7 @@ flowchart LR WS --> GS QP --> GS + BM --> GS GS --> LQ GS --> SB LQ --> AQ diff --git a/docs/plans/state.json b/docs/plans/state.json index 68ab2ca..c72bcd2 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -3,6 +3,29 @@ "updated_at": "2026-02-24", "description": "Tracks the status of all Flynn plans and implementation phases", "plans": { + "pi-embedded-manual-runtime-mode-control": { + "status": "completed", + "date": "2026-02-24", + "updated": "2026-02-24", + "summary": "Added persisted global runtime backend mode control for Pi rollout/deactivation via `/backend` command fast-path (`status`, `activate pi`, `deactivate pi`, `use config`). This keeps Flynn's configured routing as default (`config_default`) while allowing manual Pi activation/deactivation without automatic global rollback.", + "files_modified": [ + "src/commands/types.ts", + "src/commands/builtin/index.ts", + "src/commands/builtin/index.test.ts", + "src/commands/index.ts", + "src/preferences.ts", + "src/preferences.test.ts", + "src/daemon/index.ts", + "src/daemon/routing.ts", + "src/daemon/routing.test.ts", + "README.md", + "docs/architecture/AGENT_DIAGRAM.md", + "docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md", + "docs/api/PROTOCOL.md", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/commands/builtin/index.test.ts src/preferences.test.ts src/daemon/routing.test.ts + pnpm typecheck passing" + }, "pi-embedded-backend-canary-evaluation-phase": { "status": "completed", "date": "2026-02-24", @@ -6492,7 +6515,8 @@ "remaining_phases_completion": "Phase 1: 3/3 (100%) — context levels, command registry, memory structure. Phase 2: 3/3 (100%) — component registry, confidence routing, history index. Phase 3: 2/2 (100%) — adaptive memory/compaction, truthfulness/autonomy hardening", "next_up": "Track OpenClaw evolution regularly for inspiration and feature ideas", "pi_embedded_canary_spike": "completed — added optional pi_embedded backend adapter, canary-safe no-tools routing guard, backend success/fallback latency audit events, and docs/diagram updates while native remains default", - "pi_embedded_evaluation_phase": "completed — final decision rollback (applied in runtime config): Window A failed latency/fallback gates (p50 +259ms, p95 +5695ms, fallback 25%, categories: pi_module_interface/empty_assistant_text); Window B remained sample-insufficient; controlled probes verified guard coverage (pi_no_tools_mode/capability_query/attachments_present each hit once)" + "pi_embedded_evaluation_phase": "completed — final decision rollback (applied in runtime config): Window A failed latency/fallback gates (p50 +259ms, p95 +5695ms, fallback 25%, categories: pi_module_interface/empty_assistant_text); Window B remained sample-insufficient; controlled probes verified guard coverage (pi_no_tools_mode/capability_query/attachments_present each hit once)", + "pi_embedded_manual_mode": "completed — added persisted runtime `/backend` controls for manual Pi activation/deactivation (`status`, `activate pi`, `deactivate pi`, `use config`) while keeping config-driven default routing" }, "soul_md_and_cron_create": { "date": "2026-02-11", diff --git a/src/commands/builtin/index.test.ts b/src/commands/builtin/index.test.ts index 71792a0..75459e7 100644 --- a/src/commands/builtin/index.test.ts +++ b/src/commands/builtin/index.test.ts @@ -1,6 +1,6 @@ import { describe, it, expect, vi } from 'vitest'; -import { createApproveCommand, createApprovalsCommand, createContextCommand, createCouncilCommand, createDenyCommand, createElevateCommand, createModelCommand, createQueueCommand, createResearchCommand, createSkillCommand, createStopCommand, createToolsCommand, createTransferCommand } from './index.js'; +import { createApproveCommand, createApprovalsCommand, createBackendCommand, createContextCommand, createCouncilCommand, createDenyCommand, createElevateCommand, createModelCommand, createQueueCommand, createResearchCommand, createSkillCommand, createStopCommand, createToolsCommand, createTransferCommand } from './index.js'; describe('builtin /model command', () => { it('passes through the full argument string', async () => { @@ -341,3 +341,32 @@ describe('builtin /skill command', () => { expect(result).toEqual({ handled: true, text: 'ok' }); }); }); + +describe('builtin /backend command', () => { + it('passes subcommand input to backendCommand service', async () => { + const cmd = createBackendCommand(); + const backendCommand = vi.fn(() => 'Pi backend deactivated.'); + const result = await cmd.execute(['deactivate', 'pi'], { + channel: 'test', + senderId: 'user', + sessionId: 's1', + rawInput: '/backend deactivate pi', + services: { backendCommand }, + }); + + expect(backendCommand).toHaveBeenCalledWith('deactivate pi'); + expect(result).toEqual({ handled: true, text: 'Pi backend deactivated.' }); + }); + + it('returns not-available when service is missing', async () => { + const cmd = createBackendCommand(); + const result = await cmd.execute([], { + channel: 'test', + senderId: 'user', + sessionId: 's1', + rawInput: '/backend', + services: {}, + }); + expect(result).toEqual({ handled: true, text: 'Backend command is not available in this session.' }); + }); +}); diff --git a/src/commands/builtin/index.ts b/src/commands/builtin/index.ts index 77b0d55..4abd85f 100644 --- a/src/commands/builtin/index.ts +++ b/src/commands/builtin/index.ts @@ -356,6 +356,22 @@ export function createSkillCommand(): CommandDefinition { }; } +export function createBackendCommand(): CommandDefinition { + return { + name: 'backend', + description: 'Inspect or control runtime backend mode (status, activate pi, deactivate pi)', + execute: async (args, ctx) => { + if (!ctx.services?.backendCommand) { + return notAvailable('Backend command'); + } + return { + handled: true, + text: await ctx.services.backendCommand(args.join(' ').trim()), + }; + }, + }; +} + export function registerBuiltinCommands(registry: CommandRegistry): void { registry.register(createHelpCommand(registry)); registry.register(createStatusCommand()); @@ -375,4 +391,5 @@ export function registerBuiltinCommands(registry: CommandRegistry): void { registry.register(createApproveCommand()); registry.register(createDenyCommand()); registry.register(createSkillCommand()); + registry.register(createBackendCommand()); } diff --git a/src/commands/index.ts b/src/commands/index.ts index 2ac29b2..c5aa884 100644 --- a/src/commands/index.ts +++ b/src/commands/index.ts @@ -16,5 +16,6 @@ export { createApproveCommand, createDenyCommand, createSkillCommand, + createBackendCommand, registerBuiltinCommands, } from './builtin/index.js'; diff --git a/src/commands/types.ts b/src/commands/types.ts index c71b69d..48b7ee3 100644 --- a/src/commands/types.ts +++ b/src/commands/types.ts @@ -42,4 +42,5 @@ export interface CommandServices { approvePending?: (input: string) => Promise | string; denyPending?: (input: string) => Promise | string; skillCommand?: (input: string) => Promise | string; + backendCommand?: (input: string) => Promise | string; } diff --git a/src/daemon/index.ts b/src/daemon/index.ts index b123561..473948f 100644 --- a/src/daemon/index.ts +++ b/src/daemon/index.ts @@ -231,6 +231,7 @@ export async function startDaemon(config: Config, options?: StartDaemonOptions): // Restore persisted model tier const { loadPreferences, savePreference } = await import('../preferences.js'); const prefs = loadPreferences(dataDir); + let backendMode = prefs.backendMode ?? 'config_default'; if (prefs.modelTier) { modelRouter.setTier(prefs.modelTier as import('../models/router.js').ModelTier); } @@ -254,6 +255,11 @@ export async function startDaemon(config: Config, options?: StartDaemonOptions): const messageRouter = createMessageRouter({ sessionManager, modelRouter, systemPrompt, toolRegistry, toolExecutor, config, memoryStore, agentConfigRegistry, agentRouter, sandboxManager, commandRegistry, hookEngine, intentRegistry, routingPolicy, skillRegistry, skillInstaller, + getBackendMode: () => backendMode, + setBackendMode: (mode) => { + backendMode = mode; + savePreference(dataDir, 'backendMode', mode); + }, ...createConfiguredExternalBackends(config), }); channelRegistry.setMessageHandler(messageRouter.handler); diff --git a/src/daemon/routing.test.ts b/src/daemon/routing.test.ts index b688455..af6815b 100644 --- a/src/daemon/routing.test.ts +++ b/src/daemon/routing.test.ts @@ -1424,6 +1424,118 @@ describe('daemon external backend integration', () => { expect(processSpy).toHaveBeenCalled(); expect(reply).toHaveBeenCalledWith(expect.objectContaining({ text: 'native guarded response' })); }); + + it('supports manual global pi deactivation and re-activation via /backend command', async () => { + const processSpy = vi.spyOn(AgentOrchestrator.prototype, 'process') + .mockResolvedValue('native fallback response'); + const history: Array<{ role: 'user' | 'assistant'; content: string }> = []; + const session = { + id: 'telegram:pi-manual-toggle', + addMessage: vi.fn((msg: { role: 'user' | 'assistant'; content: string }) => { + history.push(msg); + return msg; + }), + getHistory: vi.fn(() => [...history]), + clear: vi.fn(), + replaceHistory: vi.fn(), + getConfig: vi.fn(() => undefined), + setConfig: vi.fn(), + deleteConfig: vi.fn(), + }; + + const commandRegistry = new CommandRegistry(); + registerBuiltinCommands(commandRegistry); + + const piBackend = { + name: 'pi_embedded', + process: vi.fn(async () => 'pi embedded response'), + }; + + let backendMode: 'config_default' | 'force_native' | 'force_pi_embedded' = 'force_pi_embedded'; + const router = createMessageRouter({ + sessionManager: { getSession: vi.fn(() => session) } as unknown as MessageRouterDeps['sessionManager'], + modelRouter: { + getAvailableTiers: () => ['fast', 'default', 'complex', 'local'], + getAllLabels: () => ({ fast: 'fast', default: 'default', complex: 'complex', local: 'local' }), + getLabel: (tier: string) => tier, + } as unknown as MessageRouterDeps['modelRouter'], + systemPrompt: 'test prompt', + toolRegistry: { + clone() { return this; }, + register: vi.fn(), + } as unknown as MessageRouterDeps['toolRegistry'], + toolExecutor: {} as unknown as MessageRouterDeps['toolExecutor'], + config: { + agents: { + primary_tier: 'default', + delegation: { + compaction: 'fast', + memory_extraction: 'fast', + classification: 'fast', + tool_summarisation: 'fast', + complex_reasoning: 'complex', + }, + max_delegation_depth: 3, + max_iterations: 10, + }, + backends: { + pi_embedded: { no_tools_mode: false }, + }, + compaction: { enabled: false }, + models: { default: { provider: 'anthropic', model: 'claude' } }, + } as unknown as MessageRouterDeps['config'], + commandRegistry, + externalBackends: { pi_embedded: piBackend } as unknown as MessageRouterDeps['externalBackends'], + defaultName: 'pi_embedded', + getBackendMode: () => backendMode, + setBackendMode: (mode) => { + backendMode = mode; + }, + }); + + const reply = vi.fn(async (_message: OutboundMessage) => {}); + + await router.handler({ + id: 'm-backend-deactivate', + channel: 'telegram', + senderId: 'pi-manual-toggle', + text: '/backend deactivate pi', + timestamp: Date.now(), + metadata: { isCommand: true, command: 'backend', commandArgs: 'deactivate pi' }, + } as MessageRouterInput, reply); + + await router.handler({ + id: 'm-after-deactivate', + channel: 'telegram', + senderId: 'pi-manual-toggle', + text: 'hello after deactivate', + timestamp: Date.now(), + } as MessageRouterInput, reply); + + expect(backendMode).toBe('force_native'); + expect(piBackend.process).not.toHaveBeenCalled(); + expect(processSpy).toHaveBeenCalled(); + + await router.handler({ + id: 'm-backend-activate', + channel: 'telegram', + senderId: 'pi-manual-toggle', + text: '/backend activate pi', + timestamp: Date.now(), + metadata: { isCommand: true, command: 'backend', commandArgs: 'activate pi' }, + } as MessageRouterInput, reply); + + await router.handler({ + id: 'm-after-activate', + channel: 'telegram', + senderId: 'pi-manual-toggle', + text: 'hello after activate', + timestamp: Date.now(), + } as MessageRouterInput, reply); + + expect(backendMode).toBe('force_pi_embedded'); + expect(piBackend.process).toHaveBeenCalledTimes(1); + }); }); describe('daemon audio routing integration', () => { diff --git a/src/daemon/routing.ts b/src/daemon/routing.ts index c2bd1dd..a17460d 100644 --- a/src/daemon/routing.ts +++ b/src/daemon/routing.ts @@ -31,6 +31,8 @@ import { dirname, resolve } from 'path'; import { loadCouncilScaffoldSafe } from '../councils/scaffold.js'; import { buildCouncilPreflightReport, shouldRunCouncilPreflight } from '../councils/preflight.js'; +export type BackendRuntimeMode = 'config_default' | 'force_native' | 'force_pi_embedded'; + function buildProviderConfigMap(config: Config): Partial> { const providerConfigs: Partial> = {}; const modelConfigs: ModelConfig[] = [ @@ -333,6 +335,8 @@ export function createMessageRouter(deps: { skillInstaller?: SkillInstaller; externalBackends?: Partial>; defaultName?: ExternalBackendName; + getBackendMode?: () => BackendRuntimeMode; + setBackendMode?: (mode: BackendRuntimeMode) => void; }): { handler: (msg: InboundMessage, reply: (response: OutboundMessage) => Promise) => Promise; agents: Map; @@ -342,6 +346,59 @@ export function createMessageRouter(deps: { const talkModeUntil = new Map(); const activeRuns = new Map(); + function getBackendMode(): BackendRuntimeMode { + return deps.getBackendMode?.() ?? 'config_default'; + } + + function getConfiguredOrFallbackDefaultBackend(): ExternalBackendName | 'native' { + return deps.defaultName ?? 'native'; + } + + function getEffectiveDefaultBackend(): ExternalBackendName | 'native' { + const mode = getBackendMode(); + if (mode === 'force_native') { + return 'native'; + } + if (mode === 'force_pi_embedded') { + return 'pi_embedded'; + } + return getConfiguredOrFallbackDefaultBackend(); + } + + function resolveRoutableBackend( + requestedBackend: ExternalBackendName | 'native' | undefined, + ): ExternalBackendName | 'native' { + if (!requestedBackend || requestedBackend === 'native') { + return 'native'; + } + return deps.externalBackends?.[requestedBackend] ? requestedBackend : 'native'; + } + + function applyBackendModeOverride( + requestedBackend: ExternalBackendName | 'native' | undefined, + ): ExternalBackendName | 'native' | undefined { + if (requestedBackend !== 'pi_embedded') { + return requestedBackend; + } + if (getBackendMode() === 'force_native') { + return 'native'; + } + return requestedBackend; + } + + function formatBackendStatusLine(activeTier: string): string { + const mode = getBackendMode(); + const configuredDefault = getConfiguredOrFallbackDefaultBackend(); + const effectiveDefault = resolveRoutableBackend(getEffectiveDefaultBackend()); + const availableExternal = Object.keys(deps.externalBackends ?? {}).sort().join(', ') || 'none'; + return [ + `Flynn is running. Active model tier: ${activeTier}. Backend: ${effectiveDefault}`, + `Backend mode: ${mode}`, + `Configured default: ${configuredDefault}`, + `Available external backends: ${availableExternal}`, + ].join('\n'); + } + async function maybeBuildTtsAttachment(responseText: string, channel: string) { if (!isTtsEnabledForChannel(deps.config, channel)) { return undefined; @@ -759,11 +816,7 @@ export function createMessageRouter(deps: { rawInput: commandInput, services: { getStatus: () => { - const requestedBackend = agentConfig?.backend ?? deps.defaultName; - const backend = requestedBackend && requestedBackend !== 'native' && deps.externalBackends?.[requestedBackend] - ? requestedBackend - : 'native'; - return `Flynn is running. Active model tier: ${agent.getModelTier()}. Backend: ${backend}`; + return formatBackendStatusLine(agent.getModelTier()); }, getTools: () => { const names = new Set(deps.toolRegistry.list().map((tool: Tool) => tool.name)); @@ -1143,6 +1196,62 @@ export function createMessageRouter(deps: { return `Session transferred to ${destinationLabel}`; }, + backendCommand: (inputRaw: string) => { + const normalized = inputRaw.trim().toLowerCase(); + if (!normalized || normalized === 'status' || normalized === 'show') { + return formatBackendStatusLine(agent.getModelTier()); + } + + if (!deps.setBackendMode) { + return 'Backend mode control is not available in this runtime.'; + } + + if ( + normalized === 'activate pi' + || normalized === 'activate pi_embedded' + || normalized === 'activate pi-embedded' + ) { + deps.setBackendMode('force_pi_embedded'); + return [ + 'Pi embedded backend activated globally.', + formatBackendStatusLine(agent.getModelTier()), + ].join('\n\n'); + } + + if ( + normalized === 'deactivate pi' + || normalized === 'deactivate pi_embedded' + || normalized === 'deactivate pi-embedded' + ) { + deps.setBackendMode('force_native'); + return [ + 'Pi embedded backend deactivated globally. Native is now forced for Pi-routed turns.', + formatBackendStatusLine(agent.getModelTier()), + ].join('\n\n'); + } + + if ( + normalized === 'use config' + || normalized === 'reset' + || normalized === 'auto' + || normalized === 'config' + ) { + deps.setBackendMode('config_default'); + return [ + 'Backend mode reset to config default.', + formatBackendStatusLine(agent.getModelTier()), + ].join('\n\n'); + } + + return [ + 'Usage:', + '/backend status', + '/backend activate pi', + '/backend deactivate pi', + '/backend use config', + ].join('\n'); + }, + getApprovals: () => { if (!deps.hookEngine) { return 'Approval gates are not enabled in this runtime.'; @@ -1409,7 +1518,7 @@ export function createMessageRouter(deps: { // If native audio IS supported, we pass attachments through unchanged — // buildUserMessage() in the agent will create native audio content parts - const requestedBackend = agentConfig?.backend ?? deps.defaultName; + const requestedBackend = applyBackendModeOverride(agentConfig?.backend ?? getEffectiveDefaultBackend()); const forceNativeForCapabilityQuery = shouldForceNativeForCapabilityQuery(messageText); const hasAttachmentsForExternalBackend = Boolean(attachments && attachments.length > 0); const selectedBackend = requestedBackend && requestedBackend !== 'native' diff --git a/src/preferences.test.ts b/src/preferences.test.ts index dbc505d..32dbddf 100644 --- a/src/preferences.test.ts +++ b/src/preferences.test.ts @@ -30,6 +30,12 @@ describe('preferences', () => { expect(prefs.modelTier).toBe('local'); }); + it('round-trips backend mode preference', () => { + savePreference(dataDir, 'backendMode', 'force_native'); + const prefs = loadPreferences(dataDir); + expect(prefs.backendMode).toBe('force_native'); + }); + it('merges preferences without overwriting other keys', () => { savePreference(dataDir, 'modelTier', 'fast'); savePreference(dataDir, 'otherKey', 42); @@ -43,4 +49,14 @@ describe('preferences', () => { savePreference(nested, 'modelTier', 'default'); expect(loadPreferences(nested).modelTier).toBe('default'); }); + + it('ignores invalid backendMode values in stored preferences', () => { + writeFileSync( + resolve(dataDir, 'preferences.json'), + JSON.stringify({ modelTier: 'default', backendMode: 'invalid-mode' }), + ); + const prefs = loadPreferences(dataDir); + expect(prefs.modelTier).toBe('default'); + expect(prefs.backendMode).toBeUndefined(); + }); }); diff --git a/src/preferences.ts b/src/preferences.ts index 5e7d612..9a60683 100644 --- a/src/preferences.ts +++ b/src/preferences.ts @@ -3,13 +3,28 @@ import { dirname, resolve } from 'path'; export interface Preferences { modelTier?: string; + backendMode?: BackendModePreference; +} + +export type BackendModePreference = 'config_default' | 'force_native' | 'force_pi_embedded'; + +function isBackendModePreference(value: unknown): value is BackendModePreference { + return value === 'config_default' || value === 'force_native' || value === 'force_pi_embedded'; } export function loadPreferences(dataDir: string): Preferences { const filePath = resolve(dataDir, 'preferences.json'); try { const raw = readFileSync(filePath, 'utf-8'); - return JSON.parse(raw) as Preferences; + const parsed = JSON.parse(raw) as Record; + const prefs: Preferences = {}; + if (typeof parsed.modelTier === 'string') { + prefs.modelTier = parsed.modelTier; + } + if (isBackendModePreference(parsed.backendMode)) { + prefs.backendMode = parsed.backendMode; + } + return prefs; } catch { return {}; }