Support persisting custom env vars in session defaults

Author: kamal

src/mcp/tools/session-management/__tests__/session_clear_defaults.test.ts

@@ -49,6 +49,19 @@ describe('session-clear-defaults tool', () => {
       expect(current.arch).toBe('arm64');
     });
 
+    it('should clear env when keys includes env', async () => {
+      sessionStore.setDefaults({ env: { API_URL: 'https://staging.example.com', DEBUG: 'true' } });
+
+      const result = await sessionClearDefaultsLogic({ keys: ['env'] });
+
+      expect(result.isError).toBe(false);
+      expect(result.content[0].text).toContain('Session defaults cleared');
+
+      const current = sessionStore.getAll();
+      expect(current.env).toBeUndefined();
+      expect(current.scheme).toBe('MyScheme');
+    });
+
     it('should clear all profiles only when all=true', async () => {
       sessionStore.setActiveProfile('ios');
       sessionStore.setDefaults({ scheme: 'IOS' });

src/mcp/tools/session-management/__tests__/session_set_defaults.test.ts

@@ -87,6 +87,18 @@ describe('session-set-defaults tool', () => {
       expect(result.content[0].text).toContain('useLatestOS');
     });
 
+    it('should reject env values that are not strings', async () => {
+      const result = await handler({
+        env: {
+          STAGING_ENABLED: 1 as unknown as string,
+        },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('Parameter validation failed');
+      expect(result.content[0].text).toContain('env');
+    });
+
     it('should clear workspacePath when projectPath is set', async () => {
       sessionStore.setDefaults({ workspacePath: '/old/App.xcworkspace' });
       const result = await sessionSetDefaultsLogic(
@@ -358,6 +370,48 @@ describe('session-set-defaults tool', () => {
       expect(parsed.activeSessionDefaultsProfile).toBe('ios');
     });
 
+    it('should store env as a Record<string, string> default', async () => {
+      const envVars = { STAGING_ENABLED: '1', DEBUG: 'true' };
+      const result = await sessionSetDefaultsLogic({ env: envVars }, createContext());
+
+      expect(result.isError).toBe(false);
+      expect(sessionStore.getAll().env).toEqual(envVars);
+    });
+
+    it('should persist env to config when persist is true', async () => {
+      const yaml = ['schemaVersion: 1', 'sessionDefaults: {}', ''].join('\n');
+
+      const writes: { path: string; content: string }[] = [];
+      const fs = createMockFileSystemExecutor({
+        existsSync: (targetPath: string) => targetPath === configPath,
+        readFile: async (targetPath: string) => {
+          if (targetPath !== configPath) {
+            throw new Error(`Unexpected readFile path: ${targetPath}`);
+          }
+          return yaml;
+        },
+        writeFile: async (targetPath: string, content: string) => {
+          writes.push({ path: targetPath, content });
+        },
+      });
+
+      await initConfigStore({ cwd, fs });
+
+      const envVars = { API_URL: 'https://staging.example.com' };
+      const result = await sessionSetDefaultsLogic(
+        { env: envVars, persist: true },
+        createContext(),
+      );
+
+      expect(result.content[0].text).toContain('Persisted defaults to');
+      expect(writes.length).toBe(1);
+
+      const parsed = parseYaml(writes[0].content) as {
+        sessionDefaults?: Record<string, unknown>;
+      };
+      expect(parsed.sessionDefaults?.env).toEqual(envVars);
+    });
+
     it('should not persist when persist is true but no defaults were provided', async () => {
       const result = await sessionSetDefaultsLogic({ persist: true }, createContext());
 

src/utils/session-defaults-schema.ts

@@ -16,6 +16,7 @@ export const sessionDefaultKeys = [
   'preferXcodebuild',
   'platform',
   'bundleId',
+  'env',
 ] as const;
 
 export type SessionDefaultKey = (typeof sessionDefaultKeys)[number];
@@ -54,4 +55,8 @@ export const sessionDefaultsSchema = z.object({
     .string()
     .optional()
     .describe('Default bundle ID for launch/stop/log tools when working on a single app.'),
+  env: z
+    .record(z.string(), z.string())
+    .optional()
+    .describe('Default environment variables to pass to launched apps.'),
 });

src/utils/session-store.ts

@@ -20,6 +20,7 @@ export type SessionDefaults = {
   preferXcodebuild?: boolean;
   platform?: string;
   bundleId?: string;
+  env?: Record<string, string>;
 };
 
 class SessionStore {