vm-service: Add optional 'scope' parameter to 'evaluate' and 'evaluateInFrame'.

runtime/vm/service/service_dev.md

 Note: this dev version of the protocol contains not yet released functionality,
 and is subject to change.
 
 # Dart VM Service Protocol 3.6-dev
 
 > Please post feedback to the [observatory-discuss group][discuss-list]
 
 This document describes of _version 3.5_ of the Dart VM Service Protocol. This
 protocol is used to communicate with a running Dart Virtual Machine.
 
@@ skipping 454 matching lines @@
 
 See [Breakpoint](#breakpoint).
 
 Note that breakpoints are added and removed on a per-isolate basis.
 
 ### evaluate
 
 ```
 @Instance|@Error|Sentinel evaluate(string isolateId,
                                    string targetId,
-                                   string expression)
+                                   string expression
+                                   map<string,string> scope [optional])
 ```
 
 The _evaluate_ RPC is used to evaluate an expression in the context of
 some target.
 
 _targetId_ may refer to a [Library](#library), [Class](#class), or
 [Instance](#instance).
 
 If _targetId_ is a temporary id which has expired, then the _Expired_
 [Sentinel](#sentinel) is returned.
 
 If _targetId_ refers to an object which has been collected by the VM's
 garbage collector, then the _Collected_ [Sentinel](#sentinel) is
 returned.
 
+If _scope_ is provided, it should be a map from identifiers to object ids.
+These bindings will be added to the scope in which the expression is evaluated,
+which is a child scope of the class or library for instance/class or library
+targets respectively. This means bindings provided in _scope_ may shadow
+instance members, class members and top-level members.
+
 If an error occurs while evaluating the expression, an [@Error](#error)
 reference will be returned.
 
 If the expression is evaluated successfully, an [@Instance](#instance)
 reference will be returned.
 
 ### evaluateInFrame
 
 ```
 @Instance|@Error evaluateInFrame(string isolateId,
                                  int frameIndex,
-                                 string expression)
+                                 string expression,
+                                 map<string,string> scope [optional])
 ```
 
 The _evaluateInFrame_ RPC is used to evaluate an expression in the
 context of a particular stack frame. _frameIndex_ is the index of the
 desired [Frame](#frame), with an index of _0_ indicating the top (most
 recent) frame.
 
+If _scope_ is provided, it should be a map from identifiers to object ids.
+These bindings will be added to the scope in which the expression is evaluated,
+which is a child scope of the frame's current scope. This means bindings
+provided in _scope_ may shadow instance members, class members, top-level
+members, parameters and locals.
+
 If an error occurs while evaluating the expression, an [@Error](#error)
 reference will be returned.
 
 If the expression is evaluated successfully, an [@Instance](#instance)
 reference will be returned.
 
 ### getFlagList
 
 ```
 FlagList getFlagList()
@@ skipping 2088 matching lines @@
 version | comments
 ------- | --------
 1.0 | initial revision
 2.0 | Describe protocol version 2.0.
 3.0 | Describe protocol version 3.0.  Added UnresolvedSourceLocation.  Added Sentinel return to getIsolate.  Add AddedBreakpointWithScriptUri.  Removed Isolate.entry. The type of VM.pid was changed from string to int.  Added VMUpdate events.  Add offset and count parameters to getObject() and offset and count fields to Instance. Added ServiceExtensionAdded event.
 3.1 | Add the getSourceReport RPC.  The getObject RPC now accepts offset and count for string objects.  String objects now contain length, offset, and count properties.
 3.2 | Isolate objects now include the runnable bit and many debugger related RPCs will return an error if executed on an isolate before it is runnable.
 3.3 | Pause event now indicates if the isolate is paused at an await, yield, or yield* suspension point via the 'atAsyncSuspension' field. Resume command now supports the step parameter 'OverAsyncSuspension'. A Breakpoint added synthetically by an 'OverAsyncSuspension' resume command identifies itself as such via the 'isSyntheticAsyncContinuation' field.
 3.4 | Add the superType and mixin fields to Class. Added new pause event 'None'.
 3.5 | Add the error field to SourceReportRange.  Clarify definition of token position.  Add "Isolate must be paused" error code.
-3.6 (unreleased) | Add 'scopeStartTokenPos', 'scopeEndTokenPos', and 'declarationTokenPos' to BoundVariable. Add 'PausePostRequest' event kind. Add 'Rewind' StepOption. Add error code 107 (isolate cannot resume). Add 'reloadSources' RPC and related error codes.
+3.6 (unreleased) | Add 'scopeStartTokenPos', 'scopeEndTokenPos', and 'declarationTokenPos' to BoundVariable. Add 'PausePostRequest' event kind. Add 'Rewind' StepOption. Add error code 107 (isolate cannot resume). Add 'reloadSources' RPC and related error codes. Add optional parameter 'scope' to 'evaluate' and 'evaluateInFrame'.
 
 [discuss-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/observatory-discuss