feat(simulator): migrate simulator tools to session defaults

Author: cameroncooke

docs/session-aware-migration-todo.md

@@ -33,22 +33,22 @@ Reference: `docs/session_management_plan.md`
 - [x] `src/mcp/tools/simulator/get_sim_app_path.ts` — session defaults: `projectPath`, `workspacePath`, `scheme`, `simulatorId`, `simulatorName`, `configuration`, `useLatestOS`, `arch`.
 
 ## Simulator Runtime Actions
-- [ ] `src/mcp/tools/simulator/boot_sim.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator/install_app_sim.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator/launch_app_sim.ts` — session defaults: `simulatorId`, `simulatorName` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator/launch_app_logs_sim.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator/stop_app_sim.ts` — session defaults: `simulatorId`, `simulatorName` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator/record_sim_video.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator/boot_sim.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator/install_app_sim.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator/launch_app_sim.ts` — session defaults: `simulatorId`, `simulatorName` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator/launch_app_logs_sim.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator/stop_app_sim.ts` — session defaults: `simulatorId`, `simulatorName` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator/record_sim_video.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
 
 ## Simulator Management
-- [ ] `src/mcp/tools/simulator-management/erase_sims.ts` — session defaults: `simulatorId` (covers `simulatorUdid`).
-- [ ] `src/mcp/tools/simulator-management/set_sim_location.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator-management/reset_sim_location.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator-management/set_sim_appearance.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator-management/sim_statusbar.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator-management/erase_sims.ts` — session defaults: `simulatorId` (covers `simulatorUdid`).
+- [x] `src/mcp/tools/simulator-management/set_sim_location.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator-management/reset_sim_location.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator-management/set_sim_appearance.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator-management/sim_statusbar.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
 
 ## Simulator Logging
-- [ ] `src/mcp/tools/logging/start_sim_log_cap.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/logging/start_sim_log_cap.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
 
 ## AXe UI Testing Tools
 - [ ] `src/mcp/tools/ui-testing/button.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).

example_projects/iOS_Calculator/.gitignore

@@ -0,0 +1,7 @@
+
+# xcode-build-server files
+buildServer.json
+.compile
+
+# Local build artifacts
+.build/

src/mcp/tools/logging/__tests__/start_sim_log_cap.test.ts

@@ -1,7 +1,7 @@
 /**
  * Tests for start_sim_log_cap plugin
  */
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import { z } from 'zod';
 import plugin, { start_sim_log_capLogic } from '../start_sim_log_cap.ts';
 import { createMockExecutor } from '../../../../test-utils/mock-executors.ts';
@@ -33,51 +33,30 @@ describe('start_sim_log_cap plugin', () => {
 
     it('should validate schema with valid parameters', () => {
       const schema = z.object(plugin.schema);
-      expect(
-        schema.safeParse({ simulatorUuid: 'test-uuid', bundleId: 'com.example.app' }).success,
-      ).toBe(true);
-      expect(
-        schema.safeParse({
-          simulatorUuid: 'test-uuid',
-          bundleId: 'com.example.app',
-          captureConsole: true,
-        }).success,
-      ).toBe(true);
-      expect(
-        schema.safeParse({
-          simulatorUuid: 'test-uuid',
-          bundleId: 'com.example.app',
-          captureConsole: false,
-        }).success,
-      ).toBe(true);
+      expect(schema.safeParse({ bundleId: 'com.example.app' }).success).toBe(true);
+      expect(schema.safeParse({ bundleId: 'com.example.app', captureConsole: true }).success).toBe(
+        true,
+      );
+      expect(schema.safeParse({ bundleId: 'com.example.app', captureConsole: false }).success).toBe(
+        true,
+      );
     });
 
     it('should reject invalid schema parameters', () => {
       const schema = z.object(plugin.schema);
-      expect(schema.safeParse({ simulatorUuid: null, bundleId: 'com.example.app' }).success).toBe(
+      expect(schema.safeParse({ bundleId: null }).success).toBe(false);
+      expect(schema.safeParse({ captureConsole: true }).success).toBe(false);
+      expect(schema.safeParse({}).success).toBe(false);
+      expect(schema.safeParse({ bundleId: 'com.example.app', captureConsole: 'yes' }).success).toBe(
         false,
       );
-      expect(
-        schema.safeParse({ simulatorUuid: undefined, bundleId: 'com.example.app' }).success,
-      ).toBe(false);
-      expect(schema.safeParse({ simulatorUuid: 'test-uuid', bundleId: null }).success).toBe(false);
-      expect(schema.safeParse({ simulatorUuid: 'test-uuid', bundleId: undefined }).success).toBe(
+      expect(schema.safeParse({ bundleId: 'com.example.app', captureConsole: 123 }).success).toBe(
         false,
       );
-      expect(
-        schema.safeParse({
-          simulatorUuid: 'test-uuid',
-          bundleId: 'com.example.app',
-          captureConsole: 'yes',
-        }).success,
-      ).toBe(false);
-      expect(
-        schema.safeParse({
-          simulatorUuid: 'test-uuid',
-          bundleId: 'com.example.app',
-          captureConsole: 123,
-        }).success,
-      ).toBe(false);
+
+      const withSimId = schema.safeParse({ simulatorId: 'test-uuid', bundleId: 'com.example.app' });
+      expect(withSimId.success).toBe(true);
+      expect('simulatorId' in (withSimId.data as any)).toBe(false);
     });
   });
 
@@ -98,7 +77,7 @@ describe('start_sim_log_cap plugin', () => {
 
       const result = await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
         },
         mockExecutor,
@@ -122,7 +101,7 @@ describe('start_sim_log_cap plugin', () => {
 
       const result = await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
         },
         mockExecutor,
@@ -148,7 +127,7 @@ describe('start_sim_log_cap plugin', () => {
 
       const result = await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
           captureConsole: true,
         },
@@ -208,7 +187,7 @@ describe('start_sim_log_cap plugin', () => {
 
       await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
           captureConsole: true,
         },
@@ -277,7 +256,7 @@ describe('start_sim_log_cap plugin', () => {
 
       await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
           captureConsole: false,
         },

src/mcp/tools/logging/start_sim_log_cap.ts

@@ -8,12 +8,13 @@ import { z } from 'zod';
 import { startLogCapture } from '../../../utils/log-capture/index.ts';
 import { CommandExecutor, getDefaultCommandExecutor } from '../../../utils/command.ts';
 import { ToolResponse, createTextContent } from '../../../types/common.ts';
-import { createTypedTool } from '../../../utils/typed-tool-factory.ts';
+import { createSessionAwareTool } from '../../../utils/typed-tool-factory.ts';
 
 // Define schema as ZodObject
 const startSimLogCapSchema = z.object({
-  simulatorUuid: z
+  simulatorId: z
     .string()
+    .uuid()
     .describe('UUID of the simulator to capture logs from (obtained from list_simulators).'),
   bundleId: z.string().describe('Bundle identifier of the app to capture logs for.'),
   captureConsole: z
@@ -30,11 +31,15 @@ export async function start_sim_log_capLogic(
   _executor: CommandExecutor = getDefaultCommandExecutor(),
   logCaptureFunction: typeof startLogCapture = startLogCapture,
 ): Promise<ToolResponse> {
-  const paramsWithDefaults = {
-    ...params,
-    captureConsole: params.captureConsole ?? false,
-  };
-  const { sessionId, error } = await logCaptureFunction(paramsWithDefaults, _executor);
+  const captureConsole = params.captureConsole ?? false;
+  const { sessionId, error } = await logCaptureFunction(
+    {
+      simulatorUuid: params.simulatorId,
+      bundleId: params.bundleId,
+      captureConsole,
+    },
+    _executor,
+  );
   if (error) {
     return {
       content: [createTextContent(`Error starting log capture: ${error}`)],
@@ -44,16 +49,23 @@ export async function start_sim_log_capLogic(
   return {
     content: [
       createTextContent(
-        `Log capture started successfully. Session ID: ${sessionId}.\n\n${paramsWithDefaults.captureConsole ? 'Note: Your app was relaunched to capture console output.' : 'Note: Only structured logs are being captured.'}\n\nNext Steps:\n1.  Interact with your simulator and app.\n2.  Use 'stop_sim_log_cap' with session ID '${sessionId}' to stop capture and retrieve logs.`,
+        `Log capture started successfully. Session ID: ${sessionId}.\n\n${captureConsole ? 'Note: Your app was relaunched to capture console output.' : 'Note: Only structured logs are being captured.'}\n\nNext Steps:\n1.  Interact with your simulator and app.\n2.  Use 'stop_sim_log_cap' with session ID '${sessionId}' to stop capture and retrieve logs.`,
       ),
     ],
   };
 }
 
+const publicSchemaObject = startSimLogCapSchema.omit({ simulatorId: true } as const).strict();
+
 export default {
   name: 'start_sim_log_cap',
   description:
     'Starts capturing logs from a specified simulator. Returns a session ID. By default, captures only structured logs.',
-  schema: startSimLogCapSchema.shape, // MCP SDK compatibility
-  handler: createTypedTool(startSimLogCapSchema, start_sim_log_capLogic, getDefaultCommandExecutor),
+  schema: publicSchemaObject.shape, // MCP SDK compatibility
+  handler: createSessionAwareTool<StartSimLogCapParams>({
+    internalSchema: startSimLogCapSchema as unknown as z.ZodType<StartSimLogCapParams>,
+    logicFunction: start_sim_log_capLogic,
+    getExecutor: getDefaultCommandExecutor,
+    requirements: [{ allOf: ['simulatorId'], message: 'simulatorId is required' }],
+  }),
 };

src/mcp/tools/simulator-management/__tests__/erase_sims.test.ts

@@ -3,15 +3,14 @@ import { z } from 'zod';
 import eraseSims, { erase_simsLogic } from '../erase_sims.ts';
 import { createMockExecutor } from '../../../../test-utils/mock-executors.ts';
 
-describe('erase_sims tool (UDID or ALL only)', () => {
+describe('erase_sims tool (ID or ALL only)', () => {
   describe('Export Field Validation (Literal)', () => {
     it('should have correct name', () => {
       expect(eraseSims.name).toBe('erase_sims');
     });
 
     it('should have correct description', () => {
-      expect(eraseSims.description).toContain('Provide exactly one of: simulatorUdid or all=true');
-      expect(eraseSims.description).toContain('shutdownFirst');
+      expect(eraseSims.description).toBe('Erases one simulator or all simulators.');
     });
 
     it('should have handler function', () => {
@@ -20,27 +19,27 @@ describe('erase_sims tool (UDID or ALL only)', () => {
 
     it('should validate schema fields (shape only)', () => {
       const schema = z.object(eraseSims.schema);
-      // Valid
-      expect(
-        schema.safeParse({ simulatorUdid: '123e4567-e89b-12d3-a456-426614174000' }).success,
-      ).toBe(true);
       expect(schema.safeParse({ all: true }).success).toBe(true);
-      // Shape-level schema does not enforce selection rules; handler validation covers that.
+      expect(schema.safeParse({ shutdownFirst: true }).success).toBe(true);
+
+      const withSimId = schema.safeParse({ simulatorId: '123e4567-e89b-12d3-a456-426614174000' });
+      expect(withSimId.success).toBe(true);
+      expect('simulatorId' in (withSimId.data as any)).toBe(false);
     });
   });
 
   describe('Single mode', () => {
     it('erases a simulator successfully', async () => {
       const mock = createMockExecutor({ success: true, output: 'OK' });
-      const res = await erase_simsLogic({ simulatorUdid: 'UD1' }, mock);
+      const res = await erase_simsLogic({ simulatorId: 'UD1' }, mock);
       expect(res).toEqual({
         content: [{ type: 'text', text: 'Successfully erased simulator UD1' }],
       });
     });
 
     it('returns failure when erase fails', async () => {
       const mock = createMockExecutor({ success: false, error: 'Booted device' });
-      const res = await erase_simsLogic({ simulatorUdid: 'UD1' }, mock);
+      const res = await erase_simsLogic({ simulatorId: 'UD1' }, mock);
       expect(res).toEqual({
         content: [{ type: 'text', text: 'Failed to erase simulator: Booted device' }],
       });
@@ -50,7 +49,7 @@ describe('erase_sims tool (UDID or ALL only)', () => {
       const bootedError =
         'An error was encountered processing the command (domain=com.apple.CoreSimulator.SimError, code=405):\nUnable to erase contents and settings in current state: Booted\n';
       const mock = createMockExecutor({ success: false, error: bootedError });
-      const res = await erase_simsLogic({ simulatorUdid: 'UD1' }, mock);
+      const res = await erase_simsLogic({ simulatorId: 'UD1' }, mock);
       expect((res.content?.[1] as any).text).toContain('Tool hint');
       expect((res.content?.[1] as any).text).toContain('shutdownFirst: true');
     });
@@ -61,7 +60,7 @@ describe('erase_sims tool (UDID or ALL only)', () => {
         calls.push(cmd);
         return { success: true, output: 'OK', error: '', process: { pid: 1 } as any };
       };
-      const res = await erase_simsLogic({ simulatorUdid: 'UD1', shutdownFirst: true }, exec as any);
+      const res = await erase_simsLogic({ simulatorId: 'UD1', shutdownFirst: true }, exec as any);
       expect(calls).toEqual([
         ['xcrun', 'simctl', 'shutdown', 'UD1'],
         ['xcrun', 'simctl', 'erase', 'UD1'],

src/mcp/tools/simulator-management/__tests__/reset_sim_location.test.ts

@@ -19,22 +19,14 @@ describe('reset_sim_location plugin', () => {
       expect(typeof resetSimLocationPlugin.handler).toBe('function');
     });
 
-    it('should have correct schema validation', () => {
+    it('should hide simulatorId from public schema', () => {
       const schema = z.object(resetSimLocationPlugin.schema);
 
-      expect(
-        schema.safeParse({
-          simulatorUuid: 'abc123',
-        }).success,
-      ).toBe(true);
+      expect(schema.safeParse({}).success).toBe(true);
 
-      expect(
-        schema.safeParse({
-          simulatorUuid: 123,
-        }).success,
-      ).toBe(false);
-
-      expect(schema.safeParse({}).success).toBe(false);
+      const withSimId = schema.safeParse({ simulatorId: 'abc123' });
+      expect(withSimId.success).toBe(true);
+      expect('simulatorId' in (withSimId.data as any)).toBe(false);
     });
   });
 
@@ -47,7 +39,7 @@ describe('reset_sim_location plugin', () => {
 
       const result = await reset_sim_locationLogic(
         {
-          simulatorUuid: 'test-uuid-123',
+          simulatorId: 'test-uuid-123',
         },
         mockExecutor,
       );
@@ -70,7 +62,7 @@ describe('reset_sim_location plugin', () => {
 
       const result = await reset_sim_locationLogic(
         {
-          simulatorUuid: 'test-uuid-123',
+          simulatorId: 'test-uuid-123',
         },
         mockExecutor,
       );
@@ -90,7 +82,7 @@ describe('reset_sim_location plugin', () => {
 
       const result = await reset_sim_locationLogic(
         {
-          simulatorUuid: 'test-uuid-123',
+          simulatorId: 'test-uuid-123',
         },
         mockExecutor,
       );
@@ -123,7 +115,7 @@ describe('reset_sim_location plugin', () => {
 
       await reset_sim_locationLogic(
         {
-          simulatorUuid: 'test-uuid-123',
+          simulatorId: 'test-uuid-123',
         },
         capturingExecutor,
       );