feat: add persisted manual pi backend mode controls

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.' });
+  });
+});

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());
 }

src/commands/index.ts

@@ -16,5 +16,6 @@ export {
   createApproveCommand,
   createDenyCommand,
   createSkillCommand,
+  createBackendCommand,
   registerBuiltinCommands,
 } from './builtin/index.js';

src/commands/types.ts

@@ -42,4 +42,5 @@ export interface CommandServices {
   approvePending?: (input: string) => Promise<string> | string;
   denyPending?: (input: string) => Promise<string> | string;
   skillCommand?: (input: string) => Promise<string> | string;
+  backendCommand?: (input: string) => Promise<string> | string;
 }

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);

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', () => {

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<Record<ModelProvider, ModelConfig>> {
   const providerConfigs: Partial<Record<ModelProvider, ModelConfig>> = {};
   const modelConfigs: ModelConfig[] = [
@@ -333,6 +335,8 @@ export function createMessageRouter(deps: {
   skillInstaller?: SkillInstaller;
   externalBackends?: Partial<Record<ExternalBackendName, ExternalBackend>>;
   defaultName?: ExternalBackendName;
+  getBackendMode?: () => BackendRuntimeMode;
+  setBackendMode?: (mode: BackendRuntimeMode) => void;
 }): {
   handler: (msg: InboundMessage, reply: (response: OutboundMessage) => Promise<void>) => Promise<void>;
   agents: Map<string, { orchestrator: AgentOrchestrator; collector: OutboundAttachmentCollector }>;
@@ -342,6 +346,59 @@ export function createMessageRouter(deps: {
   const talkModeUntil = new Map<string, number>();
   const activeRuns = new Map<string, AgentOrchestrator>();
 
+  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'

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();
+  });
 });

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<string, unknown>;
+    const prefs: Preferences = {};
+    if (typeof parsed.modelTier === 'string') {
+      prefs.modelTier = parsed.modelTier;
+    }
+    if (isBackendModePreference(parsed.backendMode)) {
+      prefs.backendMode = parsed.backendMode;
+    }
+    return prefs;
   } catch {
     return {};
   }